As the post says “Separating the content from the presentation is good practice”, but you quickly see the limits of Markdown here. It’s a nice language for situations like I’m in right now, writing a comment on a forum. It’s also sufficient for most blog posts, where it’s mostly prose and maybe the odd simple table or bit of code.
What makes Markdown nice, is that it “degrades” well. It’s still readable in its “source” format.
I mean, I can understand this
A qualitative comparison of online navigation sites
---------------------------------------------------
*Result*: [Mapquest](https://www.mapquest.com) da best, **double true**.
despite it getting a bit “nosiy”, but still better than this:
<h2 id="a_qualitative_comparison_of_online_navigation_sites">A qualitative comparison of online navigation sites</h2>
<p><em class="prose-emphasis">Result</em>:<a href="https://www.mapquest.com" role="link">Mapquest</a> da best, <strong>double true</strong></p>
But it also means that you don’t have enough ways to specify structure beyond “this is a paragraph, this is a heading, this is a table”.
Now the Haunted Spice Trade Association remarks on conventions allowing us to make and use publishing tools and linters. Such a tool could allow us to extend Markdown and tell whatever’s generating the HTML or PDF to do that according to the design we want. Specific colors, added icons, references in an index etc.
Sadly, I don’t see the conventions making good use of that. They rather seem oriented towards the usual Markdown tools producing content that’s close enough to what you might want, i.e. the output degrades, not the input.
Dungeon rooms are a good example, as they’re quite heavily structured. Their example:
### D1. First keyed location
A short description of the location, with important **things** bolded. Elaborations on these bolded **items** and any **hidden** or additional information about them will be included in the **list** below. This all sounds good.
- **Things:** An unordered list with the key terms bolded above is used to provide additional details.
- **Items:** Each list item should begin with the bolded term followed by a colon and the description.
- **Hidden:** Some items have hidden information that is described in nested line items under the term.
- These items don't need a prefixed bold term, they're assumed to be relevant to the parent item.
- The information doesn't necessarily need to be "hidden" information and might just be elaborations.
- **List:** After a term with additional details the list continues as usual.
Here in the forum this would get rendered as
D1. First keyed location
A short description of the location, with important things bolded. Elaborations on these bolded items and any hidden or additional information about them will be included in the list below. This all sounds good.
- Things: An unordered list with the key terms bolded above is used to provide additional details.
- Items: Each list item should begin with the bolded term followed by a colon and the description.
- Hidden: Some items have hidden information that is described in nested line items under the term.
- These items don’t need a prefixed bold term, they’re assumed to be relevant to the parent item.
- The information doesn’t necessarily need to be “hidden” information and might just be elaborations.
- List: After a term with additional details the list continues as usual.
Clearly made so that the output looks like the Necrotic Gnome house style. My first issue is that I’m not sure whether this should be the only “conventional” way of styling dungeon rooms, but that’s a bit of a side note. Markdown lists are also a bit of a bother to write, especially if you want to include line breaks or other elements. And, my stars and garters, all those asterisks!
But if I could depend on the fictional markdown extender, one could do it the following way:
:::dungeon-room
### D1. First keyed location
[...]
Things: No need for hyphens etc., anything in a Dungeon Room block that starts
with a word or phrase followed by a colon is considered to be a Necrotic Gnome
icon.
Items: You also don't need to bold the title manually, just like you don't
explicitly bold headings in markdown.
[...]
One of the main benefits here is that you can also deviate from such a very fixed structure. If I want to give monsters a special treatment with the purely convention-based approach, they’d need to be under the ## Stats section, whereas a more explicit structure would allow you to put them anywhere (e.g. in a dungeon room).
TL; DR: If you’re just depending on the Markdown rendering to look “close enough”, why not just go for a Google Docs template to maximize the user base? And if you go for a neat new tool, make the input format more readable and versatile. (I’d also seriously consider going for asciidoc, here, but that’s a technical nitpick)
I’m especially interested in the versatility here, as I’m not a big fan of adventures looking all the same. Yes, the Necrotic Gnome stuff looks good to me and I like its usability, but I think the whole scene would suffer if everything would look like The Hole in the Oak. Even within a game system, that’s too much (looking at you, GM Binder).
I had to learn this crazy formatting language super similar to markdown in the 80’s when I was getting trained to use an optical typesetter. hell, it might have BEEN an early version of it. I dunno. anyway, as soon as WYSIWYG layout programs came out, everyone was like, HA HA, that shit was stupid and annoying, and I am never going back.
anyway, YOU CAN’T MAKE ME GO BACK.
80s? Did the language have lots of @ signs? 
It really depends on what you’re working on. I mean, I liked my first look at PageMaker, but it was basically the digital version of scalpels and glue. Great for manual control, but not as apt for structure. You wouldn’t want to create solid documentation or even a parts catalogue with it, which is where tools like FrameMaker came in – and at a certain level, those involved weird markup languages, databases and scripting…
In my ideal world, I’d have a good, free tool where there’s both. Master pages and re-usable components (like a stat block) in a WYSIWYG environment, then some easy to write text that I can just feed to it.
Our “problem” is that especially in the OSR space, you get a lot of different layout needs. There’s the very freeform, artistic zines and the like, where basically every element is intentionally placed. Then there are the more highly structured projects, like a lot of longer adventures, with more complex room layouts, plenty of tables etc.; Maybe even the need for an index
And finally, sadly, the people whose needs remain unfulfilled, as they need something very simple, but where the output doesn’t seem to inadequate for release. Now, my personal answer to this is: Put it out there anyway, but hey, if life were that easy…
Back in the days, the community was smell, tech was limited, so very basic text files were a-ok (look at the foundation stone of the FATE juggernaut, for example). In the days of either artistic punky layout or full-color imagery and page design, many people see invisible gatekeepers.
I never understand how some can feel that just dumping lots of AI art into what looks like the default Calibri-cursed Word layout is sufficient, but that just shows that what people admire about professional products varies wildly.
Anyhoo, such Markdown-based approaches could open the way for more adventure and supplement contributions. The Homebrewery did this for 5E products that at least look close enough to the official format.
Not sure whether Cairn adventure writing has enough potential for this, especially if the products wouldn’t be adaptable for other systems (where e.g. you’d be doing a Cairn and an OSE version).
There would be the additional advantage of people being able to use different “style sheets” if the markdown original were available. So if I didn’t like the font choice or size, I could just create my own version…
I actually agree with most of what you’re saying here, I think the main difference probably stems from the goal or audience I’m thinking of.
They rather seem oriented towards the usual Markdown tools producing content that’s close enough to what you might want, i.e. the output degrades, not the input.
This is the core of it, the bubble I exist in has a lot of Obsidian, Bear Notes, static-site-generators, etc. I was working on the parsing tool mentioned in the post with the following in mind:
- All the mentioned tools are primarily markdown based, so the thought is that if you’re drafting something you’re probably doing it in markdown.
- What’s the fastest and simplest way to get to a decent looking module from that? My opinion is using conventions that get you most of the way there with a parser tool being useful but not necessary.
- I’m thinking somewhere between nothing and CAS-2, once you get past that then a heavier layout tool is way better.
But if I could depend on the fictional markdown extender, one could do it the following way:
I considered containers but wanted to stick to the idea of looking mostly good enough without a parser. Definition lists is another one that would be useful but I avoided it for similar reasons (not widely supported).
- This all kind of goes back to the idea of “a parser is nice and conventions can help with a tool like that, but I don’t want it to be necessary”.
- In a Discord conversation where this was posted, Patchwork Paladin shared their CSS for printing, and that’s a good example of what I’m thinking; no parser necessary but could be used for a little more customization.
I’d also seriously consider going for asciidoc
I like asciidoc but mentioned above most tools in my bubble are markdown based, and I’m trying to avoid maintaining multiple copies of the same content in different flavors.
I think the whole scene would suffer if everything would look like The Hole in the Oak .
I agree on this. My thought is that it’s good to have some degree of similarity so you don’t need to learn a new design language with every module you read while still leaving space for creativity.
- My ideal is for someone to do the markdown-to-HTML/PDF conversion then doodle on it.
- Some CSS flair on the HTML output goes a long way.
Thanks for clearing that up and for replying so kindly. For me, the mere mention of “we maybe could build some tools” gets me in an over-engineering frenzy
Got 'cha. Yeah, if you follow those conventions, you get a good approximation of a Necrotic-Gnome-meets-Cairn style.
That’s also a group with a high technical competency. Interesting to see what comes out of that direction.
Thanks so much for the link to the template, it’s really so simple a so good. I’m just learning markdown bit by bit.
anyone here have recommendation for a simple to use / learn publishing tool, that is linux friendly? Would be much appreciated, as that is one of my struggles.
Doesn’t exist. Scribus is not good enough or ready for prime time. Most people I know who do publishing in Linux will use Typst or LaTex, or markdown > pandoc.
I use Linux full-time but still power up a VM to use Affinity. Nothing comes close to its flexibility or ease of use (except for InDesign of course).
gotcha. I did install LaTex and immediately got overwhelmed. Then again, all the fine tuning related to publishing is overwhelming 
I’ll try and play around with conversions and see what I can come up with.
See this post!
I really wanted to get more into Scribus, as its automatization features look promising as some sort of middle ground between point-and-click and layout languages, but I got both side-tracked and disenchanted by its glacial development pace.
Affinity on Windows/Mac is kinda-sorta okay. You get something a bit more predictable and print-ready than your average word processor, for a rather good price. But it’s no RPG writing panacea either, i.e. don’t expect to get good output for free. The default styles have their quirks–I notice more and more games with ugly top-justified table cells and those huge indents after list bullet points.
It’s also not really oriented towards more structured content. Which also means (non-zine) RPG content…
For programatically producing PDFs, on Linux or elsewhere, you’ve basically got three options:
- (La)Tex: Exists since the 70s and looks that way. With its default style, you get quite readable paragraphs, but we really don’t do those anyways these days in the NSR/OSR spaces
You’re lucky if someone made a template already, as then it’s quite easy to get some house style. But I’ve only seen that for D&D 5E, AD&D 1E modules and some German stuff. This family also contains ConTeXt, which is more oriented towards print output, but has no hand-holding at all. - Typst: Yochai already pointed at the local thread. It’s the new kid on the block, trying to be a bit like LaTeX, but with both new software and language to control it. The fact that a lot of people had good results producing character sheets shows that you can achieve high levels of control over your output.
- HTML: Well, a lot of people already know how to create web pages, and this allows you some good control over the output, without looking up how to do dotted borders or drop shadows in TeX. Getting a PDF either means printing in Chrome, or using a dedicated tool like the free Weasyprint.
Now, Markdown can be put before all those languages, so doing lists, italics etc. isn’t too darn complicated. I mean, that’s what we’re doing right now, I’m glad that I can just **emphasize** things and don’t have to sound like Arnold by doing <strong>emphasize</strong>. Or making text my boyfriend in TeX (\textbf{emphasizet}). The OP is generating the HTML from Markdown with the export functionality of the notepad du jour, others might use pandoc / PanWriter.
It probably wouldn’t hurt to have more templates for some of them, so the way from Markdown to something approximating what you’d find on itch these days would be shorter.