Writing autogenerated documents with lightweight markup languages (LMLs)

A detailed analysis of existing tools for automatically generating documents from markup sources

Unai Martinez-Corral https://github.com/umarcor (Digital Electronics Design Group, University of the Basque Country (UPV/EHU))https://ehu.eus/gded
2023-07-11

THIS DOCUMENT IS WORK IN PROGRESS. IT IS A COMPENDIUM OF REFERENCES AND THOUGHTS OF THE AUTHOR GIVEN THE ASIMETRIC EXPERIENCE WITH THE DIFFERENT TOOLS. HENCE, USING IT FOR COMPARISON OF TOOLS IS CURRENTLY UNFAIR. PLEASE, TAKE IT WITH A GRAIN OF SALT.

Engineers, software developers and hardware designers need to write documentation. It might be arguable whether they need to write the docs in their final layout, or some other colleague will take care of enhancing them. Nonetheless, it is undoubtable that only the authors of some project can properly describe the complex features, implementations and motivations. As a result, tens of tools have been proposed to ease the transition from notes/comments written by developers to proper references, tutorials, how-tos, etc. Typically, the workflow starts with writing the docs in some plain text format with some specific markup or decorations. The text is either written in the sources (in software/hardware designs) or anyway distributed using the same workflow as for the codebase. Then, documentation generator tools are used to extract the content and convert/manipulate it to some other (typically prettier) format. The chain might include multiple conversions to multiple output formats (say HTML, LaTeX, PDF, EPUB, man pages, etc.).

In this document it is assumed that the reader is aware of what has been described so far. It is not the purpose of the author to convince the reader about why writing documents using markup languages and source code management (SCM) pays off (Krishnamurthy 2015) (Sablonnière 2017) (Xie 2017) (Almiray 2019). Neither it is to write an introduction to documentation as code (Docs-as-Code) or to documentation generators. By the same token, how to organize the content and/or which kind of documentation to generate is better discussed in many other references. For instance, (Procida and contributors 2020) (Procida 2017) is a very interesting approach to organizing docs into Tutorials, How-tos, Discussions and References. Write the Docs “is a global community of people who care about documentation”, where learning resources are provided and conferences are organized (Holscher and contributors 2015).

Overall, there are lots of articles about how certain users/groups/projects use some specific tool to generate some specific output format, typically involving non negligible custom (thus, specific) glue logic. Yet, all of them are likely to be feature-limited, mostly because building robust documentation tools does not pay off. It is typically a side project; people need it to have their target achieved, but the documentation system is not a target by itself. It is not until one needs to actually use one of these tools that limitations and unsupported features start to arise. It’s software, and everything can be potentially done. But there is frequently a large gap between “can be done” and “it is currently possible to do it”.

This document is an analysis of multiple documentation generators or site generators, focused on telling what is currently possible, easy or difficult to achieve.

Introduction

Different types of content need distinct features, regardless of the main workflow being common to any documentation product. Hence, what kind of outputs we want/expect to generate needs to be defined first. The author is mainly aiming at a system/workflow that fits six projects: hdl, dbhi, ghdl, VUnit, VHDL and IEEE-P1076. All of them are projects related to the VHDL language, either in Academia, in the Industry, or in the open source ecosystems in GitHub/GitLab. The following is a list of types of documents generated in such contexts:

Furthermore, on the one hand, most of the documentation is nowadays first read on screens (either a workstation, a laptop or an smartphone). Visualizing documents as web sites allows for dynamic and interactive visualization of data. On the other hand, the most thoughtful and self-contained content is better read outside and offline, thus, in paper. As a result, for any of the content types listed above (except the landing site) we want to generate two output formats, at least: HTML (website) and PDF. Some content fits other formats too, such as man pages or EPUB, but web browsers and paper are a need.

It is to be noted that in this analysis open source tools/projects are considered only. This is because documentation for the target projects is automatically generated and updated using Continuous Integration (CI) services that are public, and mostly based on OCI containers. Using non-FLOSS tools, although possible, increases the setup and maintenance burden. Moreover, a priori no vendor tool exists which can satisfy the requirement to generate all the outputs.

Last, but not least, the target is to find or compose a single workflow that suits all the types of documents. As discussed along this document, it is currently possible to generate all of them, using different sets of tools and/or accepting multiple feature limitations. But, asking users (developers) to learn multiple tools and languages providing exactly the same features is inefficient and is, thus, unlikely to succeed. On top of that, it increases the maintenance burden of the documentation system significantly.

Requirements

In order to find a single workflow that fits all the requirements, those need to be explicitly listed. In this section, requirements are organized in three categories: common/general, for HTML output only, and for PDF output only:

Common

HTML

PDF

State of the art

It is to be noted that what can be achieved is not constrained by the markup language only. Some tools and templates extend the capabilities of the standard language, while others miss some of the basic features. As commented above, potentially any markup language can be paired with a tool and a template in order to generate any desired output format. However, we are interested in solutions currently usable off the shelf.

AsciiDoc | DocBook

AsciiDoc is a document format semantically equivalent to DocBook XML, but using plain text markup. Hence, the claim is that apart from the default outputs provided by AsciiDoc tools, it is also possible to produce PDF, LaTeX, man pages, e-books, etc. by using DocBook toolchains.

AsciiDoc tooling was initially written in Python in the early 2000s. A decade later, an independent implementation written in Ruby and named Asciidoctor was released. A transpile of Asciidoctor to JavaScript using Opal is also provided, which is named Asciidoctor.js. Moreover, CLI binaries built from Asciidoctor.js are available, but not from Asciidoctor.

AsciiDoc (the format) is currently being developed in a working group of the Eclipse Foundation. The goal is to prevent further divergence between Python AsciiDoc tools and Asciidoctor.

Since Asciidoctor seems to have stronger momentum than AsciiDoc, we will focus on the former. The main generators provided by Asciidoctor are HTML5, DocBook 5 and man pages. Additional converters, such as PDF and EPUB 3, are provided through separate gems. Moreover, it uses Tilt for templating, which allows users to customize the generated output without writing a custom converter from scratch.

Asciidoctor also provides a default stylesheet and built-in integrations like Font Awesome (for icons), highlight.js, Rouge, and Pygments (for source highlighting), and MathJax (for STEM processing). The default HTML5 theme is based on Foundation.

Interesting features

Overall, the syntax looks nice, clear and powerful. It feels much readable than solutions based on markdown or restructuredtext. A built-in mechanism is provided for defining blocks with custom parameters and layout. Those are named delimited blocks. That’s a powerful mechanism that, at first sight, allows users to extend the markup language and matching templates without having to deal with the backend/generator. That is, no Ruby knowledge is required, a priori, for creating and using custom delimited block types.

The support of diagram tools is awesome. It provides a common syntax for including GraphViz, WaveDrom, Mermaid, Symbolator, PlantUML… Each figure can be generated as SVG, PNG or TXT. The figures can be written in the asciidoc sources or included from a source file.

Direct PDF generation through Prawn is supported. It allows generating nice looking PDFs while tweaking the design through CSS attributes. Features such as Asciidoctor Diagram work nicely when generating both HTML and PDF outputs. See, for instance, stnolting.github.io/neorv32 (PDF).

Drawbacks

Although several features are available through templating and delimited blocks in theory, in practice many tweaks and customisations do require writing plugins in Ruby/JavaScript or using wrappers around asciidoctor itself.

Overall, multiple HTML themes are available and it seems easy to customize the CSS output. However, the author did not find examples showcasing different templates with a clearly different structure/layout. That is, themes or skins are available, but not templates.

Multi-page HTML documents

Asciidoctor supports writing complex documents in multiple source files, using includes for composing the final structure. However, generating multiple HTML pages for one document is not supported. By default, each document is compiled to a single HTML page. That is unfortunate for very long documents, such as books or datasheets, because lots of scrolling is required.

Asciidoctor allows customising the theme/style of the HTML output and extending it, but generation of multiple pages cannot be done on top of the default template. One might generate documents/pages separatedly and then inject the TOC or wrap them together. Nonetheless, several internal cross-reference features would need to be taken care of.

Therefore, the recommendation is to develop a custom template. There are several of those in GitHub/GitLab repositories, but they tend to be very specific; so it’s best to use them as a reference. There is some info about how to achieve it in asciidoctor/asciidoctor#3948. Yet, there is no tutorial, how-to or API reference available yet.

Some users tried writing custom converters (see, for instance, owenh000/asciidoctor-multipage); however, none of them made it into the official resources nor seems to have traction.

There is a sibling project by the authors of asciidoctor named Antora, written in JavaScript. Antora allows building multi-page sites from sources located in multiple repositories (but can also be used in single repository projects). Antora uses asciidoctor.js; therefore, plugins for Antora are not the same as the ones for asciidoctor. If an extension is written in JavaScript, asciidoctor cannot be used, the JS variant is required. On the other hand, if written in Ruby, it might be possible to use it in asciidoctor and also compile it from Ruby to JS (to some extent) for usage in asciidoctor.js or Antora. Yet, there is a warning in docs.asciidoctor.org: Compile Ruby Extensions to JavaScript:

This is an advanced technique that has some limitations. The recommended way to use extensions in Asciidoctor.js is to write them directly in JavaScript.

Therefore, writing extensions which work with asciidoctor and Antora is a non-trivial task itself. It might be reasonable if one is to develop a custom workflow for some mid or large project; but it is not a quick to follow solution.

Collapsible ToC

Since multi-page HTML generation is not straightforward with asciidoctor, having collapsible items in the Table of Contents shown at the side would easen the navigation. In fact, when PDFs are generated, bookmarks are included, which allows PDF viewers to show collapsible trees. Unfortunately, the default HTML5 template in asciidoctor does not support collapsing the items in the sidebar. Again, several solutions were proposed (see asciidoctor/asciidoctor#699), but there is no official or documented solution.

LaTeX

Due to the context explained above, LaTeX output is a requirement for the author, and this workflow is not completely explained in the docs. There are brief references to a2x (which uses either Apache FOP or dblatex) and asciidoctor-fopub. Among those, dblatex seems the most adequate, because fopub requires passing XSL parameters or modifying the XSLT for altering the PDF output. There is also asciidoctor-latex, which defines an extended syntax to closely match some LaTeX features (mathematical formulas and environments); it can generate HTML or LaTeX. Still, the first class citizen in AsciiDoc seems to be HTML5 output, and much of the docs are focused on it. Unfortunately, the author did not had time yet for trying the different alternatives for generating LaTeX output. Anyway, ready-to-use templates for journal articles à la rticles seem not to be available.

Doxygen

TBW

LaTeX

LaTeX (a set of macros for TeX to interpret) is the most known plain text based document preparation system. The ecosystem has been growing and evolving for more than 50 years, and it is very used in Academia as well as for preparation and publication of books that contain complex material. It is the de facto free software standard for high quality typesetting. Traditional output formats are DVI, PostScript or PDF. Although it can be used as an standalone system, it is typically used as an intermediate format. Other tools in this analysis (e.g. DocBook, Pandoc and/or Sphinx), use LaTeX as part of the pipeline for generating PDF.

Interesting features

During so many years, several thousand packages have been contributed to Comprehensive TeX Archive Network (CTAN), which cover very general requirements and also very specific features. Support of different languages, character sets, currencies, math, etc. are some of the most known features, along with built-in automatic numbering, cross-referecing, footnotes, list generation, etc. At the same time, tex.stackexchange.com is a very active and welcoming community where package authors do typically help new users. Furthermore, thanks to drawing capabilities provided by PGF and TikZ, a whole category on their own, programatic generation of complex and very high quality diagrams, plots, etc. is one of the most relevant features. For example, in the context of hardware design, tikz-timing package allows describing waveforms.

Drawbacks

The main limitation of LaTeX is that the whole ecosystem is focused on generating printable documents. Well, actually, documents with very specific page layout requirements. Conversely, in HTML the exact rendering is not specified in the document. As a result, there is no mechanism to nicely browse a LaTeX document as an interactive HTML website. Some very interesting CSS templates exist for generating web sites that feel familiar to LaTeX documents. However, those are not expected to be matched with arbitrary LaTeX sources, but manually written instead.

A relevant exception is rendering of math equations. MathJax is a well-know open source JavaScript library that provides a display engine for LaTeX, MathML and AsciiMath notation. Almost any other tool in this analysis does use MathJax for displaying LaTeX equations in HTML.

Another relevant caveat of LaTeX is the fairly steep learning curve. This is probably due to the huge numbers of resources available with partially or apparently overlapping features. On top of that, the archaic, verbose and apparently obscure macro language makes it less appealing than other (markup) languages in this analysis. In fact, that’s one of the main motivations to use AsciiDoc/DocBook, Markdown or reStructuredText instead of plain LaTeX.

mdBook

TBW

MkDocs

TBW

Pandoc

Pandoc is a swiss-army knife (written in Haskell) for markup format conversion which can handle ~40 formats. However, default features available in Markdown are very limited, because Markdown itself is very poorly defined for elaborating complex documents. As a result, multiple plugins or extension have been written to extend both Markdown parsers and generators for certain outputs. One of such extensions is pandoc-citeproc, allowing to handle citations and bibliography using CSL stylesheets.

There are many examples putting together pandoc filters to generate PDF and/or HTML output, but using a single specific template/theme for each (Gopinath 2013) (Krishnamurthy 2015) (McLeod 2015) (Gallegos and contributors 2016) (Wagler and contributors 2017) (Ogden 2017). Sections “Downside to using Markdown?” and “Bending Markdown to your will” in (Krishnamurthy 2015) provide insightful comments; but the most explicit conclusion is shown in the figure of section “TLDR”:

(Krishnamurthy 2015) Figure 1: Comparing Word, LaTeX and Markdown
(Krishnamurthy 2015) Figure 1: Comparing Word, LaTeX and Markdown

Hence, assuming that our purpose is to support generating documents with complex custom features, the requirement to learn Haskell feels like a no-go. Nevertheless, it is a very suitable solution for not-so-complex documents, since reusing externally defined LaTeX templates is supported (unlike other tools, such as Sphinx).

Rmarkdown | RStudio

Rmarkdown is a package/system written in R to create dynamic analysis documents that combine code, rendered output (such as figures), and prose. It is focused on providing a notebook interface, similar to jupyter in the Python ecosystem. Yet, it uses pandoc under-the-hood to produce multiple output formats including HTML, PDF, Word, slideshows and more.

As with plain pandoc, several users have proposed nice templates for HTML and/or PDF output. However, as explained, in many of these tools implemented features depend not only on the markup language and the engine, but also on the template. This is specially the case with rmarkdown. Although multiple document types can be written and several output formats are supported, in practice each document will likely provide a single valid output.

For instance, rticles is a repository of 30+ templates to write scientific articles in rmarkdown, as explained in Chapter 13 of (Xie, Allaire, and Grolemund 2018). However, there are no matching HTML templates. Furthermore, some of the existing templates require some features (e.g. cites) to be written in LaTeX. As a result, in most practical cases which use not only most basic features, different rmarkdown sources are required if multiple outputs (PDF and HTML) are to be generated.

Probably the most powerful and, at the same time, limiting feature of rmarkdown is precisely that it is based on R, and R knowledge is required to use it. Precisely, for table and figures to be properly identified as such, knitr needs to be used. That is, they need to be dynamically generated in R. Writing the content in plain markdown syntax will have it shown, but not semantically defined as an environment, with a label and a caption.

Distill

Opposite to rticles, distill is a publication format for scientific and technical writing, native to the web1. That is, it provides some features which are not supported by any matching template for LaTeX/PDF output. Still, it is a very nice looking template/theme, with some interesting and useful features.

Interesting features
Caveats

Tufte Handouts

Tufte Handouts allows to generate matching HTML and LaTeX/PDF outputs with the style that Edward Tufte uses in his books and handouts. As far as the author is aware, this is the only package/template that provides matching styles for HTML and PDF output.

Interesting features
Caveats

Overall, Tufte is a very interesting showcase of a single rmarkdown source being used to generate consistent HTML and PDF outputs. However, the style is very opinionated. It would be interesting for Tufte’s HTML output to be compatible with rticles templates.

Bookdown GitBook

Bookdown is an R package that provides a ready-to-use engine to combine multiple rmarkdown documents as chapters of a single publication. It generates HTML, LaTeX/PDF, EPUB and/or Word output. It uses some built-in template(s) for LaTeX that allows to generate documents of type article or report/book. For HTML output, the default style is GitBook, based on gitbook.com.

Bookdown supports some other alternative styles for HTML output. Precisely, there is an style based on Bootstrap. It is also possible to use the Tufte style. However, other rmarkdown templates need to be specifically adapted for them to be used with bookdown. By the same token, although docs state that rticles can be used for bookdown’s pdf_book output, in practice modifications are required.

Overall, bookdown provides nice default HTML and PDF outputs2, even though the styles are not particularly matching.

Interesting features
Caveats

Summarizing, bookdown’s GitBook template provides the best navigation features in the HTML output. It would be useful to have the interesting features available in distill or tufte.

Regarding the PDF output in bookdown, there is a repository named thesisdown where the LaTeX output is customized for 30+ institutions.

Pagedown

Pagedown is another package for markdown that tries to bypass LaTeX by defining the layout in CSS and relying on web site printing tools to generate PDF. While the approach is interesting, it is not suitable for the types of documents that are the target of this analysis. Precisely, in order to generate an HTML layout that can be printed, all the dynamic features that take advantage of an interactive platform are lost. In practice, the result is similar to generating a PDF only, and then viewing it in a browser. Hence, this generator might be used as a replacement of LaTeX output, but complemented with another HTML output. Trying to use arbitrary outputs with the same rmarkdown source has the caveats explained above.

It is to be noted that this package/workflow is better understood as a trend that expects LaTeX to be dead soon. In (Xie 2018), the author of pagedown argues that “it (LaTeX) will definitely survive for a few more years (maybe twenty or thirty years), but I believe HTML has much more potential to prosper”. However, at the same time, it is acknowledged that, “in terms of typesetting, HTML cannot beat LaTeX, but it all depends on how good you want the typesetting to be”. The website of page.js is a very illustrative example: while the output is nice and clean, the quality is “just” good enough, and many features are missing as a web site.

Blogdown

Blogdown is an R package that transforms rmarkdown sources into a content structure for Hugo. Hence, it is an interesting solution for R users that want to keep the rmarkdown workflow they are used to, when generating blog sites. However, in the context of this analysis, features are equivalent to the ones offered by Hugo alone. That is multiple HTML templates are available, but generating PDF through LaTeX (or pandoc) is not supported.

ReLaXed

ReLaXed is a tool written in JavaScript. The sources of the documents are written in a custom minimal syntax similar to Markdown or LaTeX, supporting typical features such as LaTeX-style mathematical equations (via MathJax), interactive plot/diagram generation through existing JavaScript or CSS frameworks, etc. Examples are really nice looking and modern. Unfortunately, similar to pagedown or paged.js, this is a very interesting approach to avoid LaTeX, but it is not suitable for the use cases with most complex typesetting requirements.

This workflow seems to be specially suited for people familiar with web technologies, which know nothing about LaTeX. However, the learning curve for those who need to learn HTML, Pug, CSS and JavaScript doesn’t seem to be easier.

Sphinx

Sphinx is a documentation generator written in Python by the Python community and initially focused on documenting Python projects. It converts reStructuredText files into HTML websites and other formats, such as PDF (through LaTeX), EPUB, texinfo and man. Nonetheless, other markup languages (say Markdown) are supported through extensions. Sphinx uses Jinja for HTML templating, which is a text-based engine, inspired by Django templates. Yet, “the latex builder does not benefit from prepared themes” (Brandl and contributors 2008). A limited interface is provided for customization of some LaTeX options and elements, but the template is fixed.

Interesting features

The main advantage of Sphinx is powerful cross-reference support. Unlike Markdown, reStructuredText supports importing/including other sources and referencing the headers across them. Moreover, sphinx.ext.intersphinx allows referencing headers/sections in other independently built and published projects, by preserving the same syntax used for internal references. Overall, it is a great fit for distributed ecosystems.

Moreover, it supports writing specific blocks of source for some output format only, thus allowing next to each other description of different visualizations of the same data/info.

It is written in Python and was born in the Python community. Due to the momentum of the Python language in several areas, Sphinx is probably the most used static site generator. Read The Docs is a hosted service based on Sphinx, which provides integration with GitHub and other forge services; it is the documentation solution used by thousands of projects. Furthermore, Sphinx is used for documenting the Linux Kernel (see lwn.net/Articles/692704). As a result, there are dozens of extensions for all kinds of integrations.

Sphinx is the most used documentation generation tool in the open source EDA tooling ecosystem. The following sites are based on Sphinx:

Pybtex!

Drawbacks

On the one hand, having a fixed LaTeX template makes Sphinx unsuitable for documents that need a pre-defined custom style. At the same time, as in AsciiDoc, multiple HTML themes/skins exist, but most of them feel like cosmetic variations of the same base template. The de facto standard theme (Snider, Carlisle, and contributors 2013) was created several years ago, with a framework and a layout/design that are getting outdated (last updated on Jan 2015 (Snider and contributors 2013)). Moreover, maintainters refuse to support the theme being used outside of the service maintained by themselves. Some nice and more up to date themes exist, but unfortunately not all of them are open source. Thankfully, the communty is reacting and recently a very interesting solution based on Bootstrap was published: Sphinx TYPO3 theme (Bless and contributors 2020).

On the other hand, although arguable, it is a common feeling that reStructuredText is less comfortable to get used to and to remember than Markdown. This is coherent with the fact that Markdown is more feature limited. Nevertheless, this should not be dismissed when approaching writers with different levels of expertise.

Regarding extraction of documentation from sources, Sphinx does a nice job with docstrings defined in Python sources. It can navigate the hierarchy of a package/library and generate the documentation for each module, function, parameter, etc. There are language domains for C and C++ too; however support of other languages is quite limited. sphinxcontrib-vhdldomain and pyVHDLParser are early work to add a domain for VHDL, as an extension to Sphinx.

Even though it is possible to write extensions, it’s not something that the average user/developer can do easily. It is a low-level API that exposes many of the internals and requires a deep understanding of the tool (Sphinx contributors 2007). In fact, extensions can be builders written from scratch, roles, directives, markup extensions or hooks, all under the same umbrella.

With regard to importing Markdown sources, it is supported but feature limited, due to the distinc feature set of the language.

ToDo

typst

Static Site Generator (SST)

In the last 5-10 years there has been a trend to migrate web sites from engines with heavy logic to static site generators, thus trading data volume for runtime computation. Static sites are web sites composed of multiple standalone pages that are delivered to the browser exactly as stored, in contrast to dynamic web pages which are generated and typically customized for each user. In-between, static sites with JavaScript can provide some dynamic features, thus blurring the distinction. A term used in this context is Jamstack, which corresponds to JavaScript, APIs, and markup.

Nevertheless, it is not the purpose of this document to introduce static site generators. In this analysis, the most relevant issue to underline is that SSTs are primarily meant for generating HTML web sites. As a result, all PDF generation capabilities, if possible, are an afterthought. Typically, PDF outputs are equivalent (if not worse) to the results obtained with pagedown, paged.js or ReLaXed.

Still, there are some SSTs which are worth introducing:

Golang (Hugo)

TBW

Ruby (Jekyll)

TBW

JavaScript/TypeScript (Vue, React)

TBW

Waveforms

Real-time collaboration

Summary and conclusions

The list of supported output formats (as far as the author is aware) is listed in Table 1. Note that Static Site Generator (SST) is not a single tool, but it stands for a whole family of projects.

Table 1: Supported output formats in multiple languages/tools.
HTML LaTeX man EPUB
Static Site Generator Yes ? ? ?
AsciiDoc Yes Yes Yes ?
Doxygen Yes Yes Yes No
MkDocs Yes ? ? ?
Pandoc Yes Yes ? Yes
Sphinx Yes Yes Yes Yes

Most projects add custom extensions in the parser, in the generator and in the default template. Hence, it is almost impossible to reuse the same source for multiple tools, or even for multiple templates using the same tool. Potentially, multiple templates could exist which provide the same features as the default, but in practice that is not the case.

Notable missing features

TBW

References

Almiray, Andres. 2019. “[VDM19] Asciidoctor: Because Writing Docs Does Not Have to Suck.” 2019. https://www.youtube.com/watch?v=290zVUmSEJQ.

Bless, Martin, and contributors. 2020. “Sphinx Typo3 Theme.” 2020. https://github.com/TYPO3-Documentation/sphinx_typo3_theme.

Brandl, Georg, and contributors. 2008. “Sphinx: LaTeX Customization.” 2008. https://www.sphinx-doc.org/en/master/latex.html.

Gallegos, Santos, and contributors. 2016. “IEEE Paper Template for Pandoc.” 2016. https://github.com/stsewd/ieee-pandoc-template.

Gopinath, Rahul. 2013. “A Skeletal Project to Convert a Paper Written in Markdown Format to Ieee Style Paper Submission in Pdf.” 2013. https://github.com/vrthra/markdown-ieee-pdf.

Holscher, Eric, and contributors. 2015. “Write the Docs.” 2015. https://www.writethedocs.org/.

Krishnamurthy, Dheepak. 2015. “Writing Technical Papers with Markdown and Pandoc.” 2015. https://blog.kdheepak.com/writing-papers-with-markdown.html.

McLeod, Clay. 2015. “Simple Markup to Produce Academic Publications Using Pandoc.” 2015. https://github.com/claymcleod/pandoc-academic-publication.

Ogden, Max. 2017. “How to Make a Scientific Looking Pdf from Markdown (with Bibliography).” 2017. https://gist.github.com/maxogden/97190db73ac19fc6c1d9beee1a6e4fc8.

Procida, Daniele. 2017. “What Nobody Tells You About Documentation.” 2017. https://www.youtube.com/watch?v=t4vKPhjcMZg.

Procida, Daniele, and contributors. 2020. “DIVIO: The Documentation System.” 2020. https://documentation.divio.com/.

Sablonnière, Hubert. 2017. “Documentation as Code (Explained to My Dad).” 2017. https://www.youtube.com/watch?v=ggBv_pZDu0c.

Snider, Dave, Aaron Carlisle, and contributors. 2013. “Read the Docs Sphinx Theme.” 2013. https://github.com/readthedocs/sphinx_rtd_theme.

Snider, Dave, and contributors. 2013. “Wyrm, a Collection of Responsive, Static Assets That Work Well with Form or Document Heavy Sites.” 2013. https://github.com/snide/wyrm.

Sphinx contributors. 2007. “Sphinx: Developing a "Todo" Extension.” 2007. https://www.sphinx-doc.org/en/master/development/tutorials/todo.html.

Wagler, Pascal, and contributors. 2017. “Eisvogel, a Pandoc Latex Template to Convert Markdown Files to Pdf or Latex.” 2017. https://github.com/Wandmalfarbe/pandoc-latex-template.

———. 2018. “In Html and the Web I Trust.” 2018. https://yihui.org/en/2018/07/in-html-i-trust/.

Xie, Yihui, J. J. Allaire, and Garrett Grolemund. 2018. “R Markdown: The Definitive Guide.” 2018. https://bookdown.org/yihui/rmarkdown/.

  1. Precisely, it is the theme/template used in this document.↩

  2. See, for example, larsasplund.github.io/github-facts↩

References

Corrections

If you see mistakes or want to suggest changes, please create an issue on the source repository.

Citation

For attribution, please cite this work as

Martinez-Corral (2023, July 11). Writing autogenerated documents with lightweight markup languages (LMLs). Retrieved from https://dbhi.github.io/docascode

BibTeX citation

@misc{martinez-corral2023writing,
  author = {Martinez-Corral, Unai},
  title = {Writing autogenerated documents with lightweight markup languages (LMLs)},
  url = {https://dbhi.github.io/docascode},
  year = {2023}
}