Regarding the change to Markdown for the Paragraph tool in Foundry 3

Backstory time: The rendering engine that RapidWeaver, and in turn Stacks, uses for Styled Text does not generate proper semantic code. This isn’t a knock on either, it is just a fact. And it has been this way for a very long time. It is a tricky situation for both RapidWeaver and Stacks as they risk breaking things to change it.

This rendering engine is what Foundry 2 used previously, with a few hacks to make the code slightly better, but still not correct. If you add a Text tool that comes with the Stacks plugin, which uses this Styled Text rendering engine, to a page and then look at the code it generates, you’ll see something like this:

<div id="stacks_in_1" class="">
	<div id="stacks_out_2" class="stacks_out">
		<div id="stacks_in_2" class="stacks_in text_stack">Lorem ipsum dolor sit amet, sapien platea morbi dolor lacus nunc, nunc ullamcorper. Felis aliquet egestas vitae, nibh ante quis quis dolor sed mauris. Erat lectus sem ut lobortis, adipiscing ligula eleifend, sodales fringilla mattis dui nullam. Ac massa aliquet.</div>
	</div>
</div>

Note that there are no paragraph tags used at all and if we add a second paragraph of text within that same default Text tool you’ll get this:

<div id="stacks_in_1" class="">
	<div id="stacks_out_2" class="stacks_out">
		<div id="stacks_in_2" class="stacks_in text_stack">Lorem ipsum dolor sit amet, sapien platea morbi dolor lacus nunc, nunc ullamcorper. Felis aliquet egestas vitae, nibh ante quis quis dolor sed mauris. Erat lectus sem ut lobortis, adipiscing ligula eleifend, sodales fringilla mattis dui nullam. Ac massa aliquet.<br><br>Lorem ipsum dolor sit amet, sapien platea morbi dolor lacus nunc, nunc ullamcorper. Felis aliquet egestas vitae, nibh ante quis quis dolor sed mauris. Erat lectus sem ut lobortis, adipiscing ligula eleifend, sodales fringilla mattis dui nullam. Ac massa aliquet.</div>
	</div>
</div>

Instead of paragraph tags <p> to separate the two blocks of text it inserts two <br> break tags instead. This is not proper semantic HTML markup.

Foundry 3: With that back story out of the way, let’s jump forward and look at Foundry 3’s Paragraph tool. The F3 Paragraph tool uses RapidWeaver’s, and in turn Stacks’, Markdown rendering engine, as it does in fact produce proper semantic code, which was a goal of this Foundry 3 re-write. Let’s take a look at what the F3 Paragraph tool produces below. I’ve added two blocks of text into one Foundry 3 Paragraph tool, and this is the resultant output:

<p>Lorem ipsum dolor sit amet,consectetur adipiscin elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco commodo consequat. Duis aute irure dolor in reprehenderit in fugiat nulla pariatur. Excepteur sint occaecat non proident, sunt officia deserunt mollit anim id est laborum.</p>
<p>Lorem ipsum dolor sit amet,consectetur adipiscin elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco commodo consequat. Duis aute irure dolor in reprehenderit in fugiat nulla pariatur. Excepteur sint occaecat non proident, sunt officia deserunt mollit anim id est laborum.</p>

You’ll notice the text is properly wrapped in <p> tags, unlike the Styled Text rendering engine, and instead of just putting <br> breaks produce empty lines to create line spacing between blocks of text, a new set of <p> tags is used for the subsequent paragraphs. This is properly semantic HTML markup.

So where’s the problem here? Many users have grown accustomed to using the Styled Text Engine in RapidWeaver & Stacks, and the Stacks text editing for that engine provides buttons for bold, italic, underline and more, as well as provides a link picker dialogue box for adding links so you can more easily pick internal pages, or external URLs.

The Stacks editor for Markdown however is lacking some of these features. I don’t have control over this unfortunately. So it is a very tricky spot. I either provide customers with a tool that creates the best code for their website but offers a slight learning curve and adaptation period, or provide them with a tool that has a better interface inside the Stacks editor and you end up with lesser code for your site. I chose the former when writing Foundry 3 as I felt it the more beneficial for users.

If you all want a Styled Text based Paragraph tool I can write that and integrate it into Foundry 3 when the influx of support generated by the Foundry 3 launch dies down. But please know that it will not produce proper semantic code.

7 Likes

It is always fun to learn something new. Markdown is very intuitive and easy to learn. It actually makes more sense than plain html markup.

The text window I am typing in actually uses Markdown, I bet you didn’t know it. :wink:
Anyway, here is the OG source for Markdown from the man who created. This is where I go if I need guidance.

1 Like

I am happy with the new Paragraph tool, just need to remember to use relative paths for internal links so flagging that here.

I think using markdown is a great choice. I use markdown all the time for my own writing so I guess its no real issue for me. You can also insert HTML tags as well. For instance I use the SPAN tag to colour a selection of text within the paragraph. I wrote the full tag syntax here but it hides it when posted. :smiling_face_with_tear:

The only annoyance that I experience with the new Paragraph tool, is that inline URLs can’t be easily added. You now have to provide the path yourself after you click the button to add the markdown syntax for URLs. In F2 you simply highlighted a word or a sentence and clicked the URL button to navigate to the page in your project you’d want to link to.

It’s a minor annoyance though.

1 Like

I’m not a huge fan of the Stacks interface for Markdown. I think there’s a lot of room for improvement there for sure. But overall Markdown is the better choice for the code side of things.

2 Likes

Is there any way to enlarge the edit view in PARAGRAPH? For my eyes it is a real strain! I’m thinking others wish there was an enlargement button?

That is not within my control whatsoever. You’d need to speak with YourHead Software about that.

Fwiw, Isaiah, the Stacks developer, has mentioned that he is not able to do this with the current RW API. He also mentioned that it’s one of the first things he did when he started working on the stand-alone Stacks app.

1 Like

Hi, for this I use the CTRL key and the mouse wheel to enlarge the screen. And back when I am done. For me, this is the quickest way to edit text which is a bit small in these windows.

1 Like

Fueleman, I’ve tried every key combination, but can’t enlarge the “edit view” in Paragraph! More details, please!
Bye R@y

Hi, sure: You can set this in the Accessibility settings in your Mac.

1 Like

So you can select how you want to do that - using the keyboard, trackpad or mouse. I work with the mouse, so I use that one.