Configure markdown style interpretation

[jg3]

Hello - super-noob disclaimer: redirect or educate me, TIA.

Q: How can I control what HTML/CSS results from my markdown source data?

Is there a way to define in the Liquid/Nunjucks layout that given Markdown syntax should be rendered with a particular CSS class or selector?

For example maybe there's a second-level header:

## Hello World!

becomes:

<h2>Hello World!</h2>

...and in the CSS there's a section that might say:

h2 {
  font-size: 4.2rem;
  line-height: 110%;
  margin: 2.8rem 0 1.68rem 0;
}

What I would like to do, is re-define the way all second-level headers show up. Now, i can think of a few ideas, but because I can barely spell CSS I'm not sure which of these are might be bad ideas and why.

Some ideas:

1. Edit the .css and change what's inside the h2 selector to define the look I want (not good if it's not my stylesheet)
2. Create another stylesheet that loads later and updates the h2 selector (write my own stylesheet? scary.)
3. Somehow define in the Liquid/Nunjucks layout that second-level headers should be rendered as something other than <h2> with some class selector maybe?

Is this last idea possible?

And what would be a good way to handle only changing the style of an element on an occasional or one-off basis? Could I, say highlight some text by calling a CSS selector using some Liquid? (and at that point why not just HTML inline styling?)

Thanks for any insights.

--jg3

[pdehaan]

I'd probably go with option 2:

Create another stylesheet that loads later and updates the h2 selector (write my own stylesheet? scary.)

I think that's the typical approach if you're using something like a CSS reset and want to customize your site with your own custom styles or use Tailwind, etc.

[jg3]

Thank you! That's the direction I'm taking ... a few CSS intro pages and I'm off and running with my own nascent CSS 😃, but I don't understand the relationship between a markup in the Markdown source page and what HTML / class / CSS gets applied. In my example a line starting with## will get tagged H2 and the corresponding CSS, but what if I wanted to create(?) a Markdown syntax, say a line starting with ==> will indicate that a paragraph should [ have some specific CSS applied | be indented and wrapped in a shaded box with a bold NOTE: at the top ]?

(I went and learned a bit about Tailwind and I think it's a little advanced for me for now)

[pdehaan]

I agree that Tailwind is usually overkill unless you need it.

Not sure what to recommend for something like ==> . You're basically inventing a new version of Markdown, and one that would get very messy verry fast.
If it were my site/project, I'd probably try something like https://www.npmjs.com/package/markdown-it-attrs with Eleventy (probably start with https://www.11ty.dev/docs/languages/markdown/#add-your-own-plugins) and then you can probably do something like this:

I am a custom alert paragraph note thing {.alert-info}

Or create some sort of shortcode that you can use if you're talking about global alert components that you'd want to use in multiple places.
For example, we can look at the Eleventy site at https://raw.githubusercontent.com/11ty/11ty-website/main/src/docs/languages/markdown.md. Note that near the top of that Markdown file there is some code like this:

{% callout "info" %}
Markdown files are by default pre-processed as Liquid templates. <a href="/docs/config/#default-template-engine-for-markdown-files">You can change this default in your configuration file</a> (or disable it altogether). To change this for a single template and not globally, read <a href="/docs/languages/">Changing a Template’s Rendering Engine</a>.
{% endcallout %}

It's a bit tricky to follow since it was converted to a .webc component in newer versions of the documentation, but if we look at an earlier version of the website, we can see the code for the paired shortcode in the .eleventy.js config file:

https://github.com/11ty/11ty-website/blob/7a34bf477fefdd3319dd62bbaf83c82976eecead/.eleventy.js#L575-L582

	eleventyConfig.addPairedShortcode("callout", function(content, level = "", format = "html", cls = "") {
		if( format === "md" ) {
			content = mdIt.renderInline(content);
		} else if( format === "md-block" ) {
			content = mdIt.render(content);
		}
		return `<div class="elv-callout${level ? ` elv-callout-${level}` : ""}${cls ? ` ${cls}`: ""}">${content}</div>`;
	});