Consider using AsciiDoc as an alternative to Markdown

[eiderweb]

I appreciate that this is not a timely suggestion, but having wrestled with Markdown document projects a lot myself, for a large, multi-sectioned document like this you may find that AsciiDoc is better choice than Markdown for long term maintenance of the material.

Whether that would be a feasible or worthwhile change to make at this stage of the project will depend on your plans for future revisions / publication versions of QuestWorlds and the maintenance of the SRD, as well as your reasons for selecting Markdown in the first place.

Specific advantages to using AsciiDoc that I can see for you:

• You can add identifiers to sections and use these in links, instead of manually maintaining link refs as text
  • This would avoid issues like #147
  • This would also make the section references clickable in the generated PDF and HTML docs, making it easier for readers to navigate around the document
• It's not hugely different to Markdown, and it is also supported by GitHub for rendering within the repo
• It is much better than Markdown at formatting and rendering tables
• You can include:: other asciidoc input files in a file
  • Thus you could have a top-level asciidoc file (with a TOC reference) that pulls in the individual section files, or chapter files that pull in the individual section files
  • This means that it would render as a single continuous file in GitHub, while managing changes to files individually
  • You also wouldn't need the create-markdown.sh script to build a single input file
  • You can use AsciiDoctor-PDF as an alternative way to generate PDFs
  • This has a rich document theme feature, which can be used to fine-tune the layout of the output document (in the same way that you currently use .tex files with Pandoc)

However, I appreciate that this is a big change to contemplate at this stage of the project, so I won't be at all offended if you reject my suggestion!

Note that you can use pandoc to convert the files from markdown to asciidoc, so this isn't as big a manual task as you might fear, but there are some notable conversions that pandoc handles badly, so there would be some manual intervention required. However, you could check for unintended changes after conversion by comparing HTML versions of the doc generated from both the asciidoc and the original markdown source.

Sadly you can't currently use pandoc to generate PDFs from AsciiDoc source, as pandoc does not (yet) provide a reader (only a writer), so there would alos be work involved in switching from pandoc/text to AsciiDoctor-PDF.

I use markdown, AsciiDoc and AsciiDoctor-PDF in my day job, so I would be happy to help with a) converting to adoc and b) PDF wrangling if you can see some value in this change. I could also make a quick prototype version to illustrate the benefits.

[iancooper]

However, I appreciate that this is a big change to contemplate at this stage of the project, so I won't be at all offended if you reject my suggestion!

At this point, it is too much, but we can bear this in mind for the future. Thanks for suggesting, I will do some digging