Something that’s missing from Zola’s templating – and most of Markdown’s standards – is the ability to introduce user-defined attributes – classes, IDs, style etc. – to Markdown’d content.
For example, it would be very useful indeed to be able to add class to a section of text that isn’t otherwise stylable, i.e. not rendered within an element like <em>text</em>. Not all content is going to be perfectly renderable with an HTML template alone: sometimes the content itself will have to have internal definitions.
This inevitably adds complexity to parsing. In return, it adds a fine degree of control over one’s content, in ways shortcodes or includes cannot deliver.
There are examples of doing so online, as well as options to how to do so. The former is simpler, the latter is more powerful. Both address ambiguities and provide examples of achieving some difficult results. Both are JS-based, but I’m sure it would be perfectly possible to render the same code in Ruby.
This is possible to do in HTML currently, so this isn’t a hot or urgent request. However, writing content in Markdown is the gist of Zola’s process, and the above libraries are good examples of how to make getting the same results easier within the same mental model. In other words, native is easier.
Zola already features a single subfeature of the proposition: adding IDs to headings using the {#id} syntax. I’d assumed initially that this also means the rest of the similar syntax is available to me; that assumption has proven to be false.
Kramdown, a Ruby Markdown parser, enables this feature with a different syntax: {: .class #id}. This is acceptable, if a little wordier than necessary, with the colon and the space after it.
1 Like
Maybe something like {text this is applied to}{#id .class} for selective text and syntax like *my para*{#id .class} for the whole element.
Yes, that would be fine.
There’s a link somewhere in the first example to a JS module that allows making <span> elements in Markdown by wrapping them in square brackets. This would allow “styling” regular text.
I like the curly-brackets suggestion. I wonder if it would make sense, given that Zola already uses a lot of those for different tags. You want to avoid confusion whereever possible, generally.
Just thinking applying to lists:
- some text {#fist}
- more test {#second}
{#the-list}
| a {#cell11} | b {#cell12} | {#row}
{#the-table}
Another interesting case:
***Some bold italic text*{#ID1}**{#ID2}
***Some other bold italic text**{#ID3}*{#ID2}
```
in main(void) {}
``` {#simple-code}
You might enjoy the fact that your thoughts about handling ambiguous cases align with those of the creator of the first example. They’d elaborated on a few cases that may cause trouble for new users, like applying such styling to each of the nested lists.
Their examples don’t delve into applying the idea to tables, so I’m glad you paved the grounds for it.
If you want styling beyond the markdown standard and your own CSS styling of those standard elements, Zola shortcodes cover nearly all cases. And for small style changes, markdown lets you put raw HTML in your markdown.
So, I thought I’d shared my particular concerns about the limitations of the current process in this thread, but it appears that I hadn’t, so here goes:
Shortcodes are suitable for inserting complex HTML structures. Streamed content is a good example: it’s generally rather involved. Pre-generated content sections are a good example, too.
They’re unusable for partial element insertion (e.g. only the opening tag with its associated attributes):
- if you want to insert the opening tag, you’ll have to insert the closing tag manually as well, which is excessive cognitive load
- to my knowledge, shortcodes don’t support multiline property values
- even when they do, you risk losing control of the output by, say, being unable to differentiate between types of input content, e.g. multi-line list items or table cells
The latter also touches upon my specific case: casting classes onto lists. There’s no native access to the list element in Markdown: all you get is list items, which render their parent upstream. Using HTML doesn’t work in this case:
- Markdown is not rendered inside HTML elements in Zola
- even if it did, it would only create an embedded “clean” list element within your HTML one, defeating the purpose
- you could use shortcodes to render both the list and its items, each with its own shortcode, but at this stage I have to wonder why I’m even relying on Markdown for default rendering
The bigger issue here is that there isn’t a meaningful option to do this inline, within Markdown itself. Put plainly, Markdown is easier to write than raw HTML. It’s more comfortable if your goal is to render content rather than layout.
Here we’re dealing with building static pages with templates. Not all content could be precomposed into specific templates: sometimes the text itself could require additional features. Special classes for a particular line, or a list, or a mathematical equation. Being able to do it with HTML is powerful. Having to do it with HTML is limiting.
You could also develop shortcodes for specific cases, but isn’t it better to be able to do this kind of stuff natively, without having to think about the implementation? This is what Markdown is for, isn’t it? So, I’d rather see the allowed Markdown expanded. If I should be able to, I’d like to help, too: I’m going to be using it frequently, after all. Where do I start?
1 Like