aproragadozo / mkdocs-poc

Testing the MkDocs Static Site Generator

What this is

This is a proof of concept for a documentation site that is automatically deployed whenever a GitHub repository is updated with Markdown content.

It currently uses python-markdown, MkDocs, git subtrees, GitHub Pages, and Travis CI.

Review comment support is a planned feature (probably using GitHub Issues).

Site Requirements

• The documentation site should support multiple GitHub repositories - the site should be re-deployed if any of the dependent repositories are updated.

  This is currently supported with git subtrees. Not ideal, because the editor needs to manually fetch updates from dependent repositories, but I haven't yet found a better solution. (Except for Antora, which only supports AsciiDoc as content format.)

• The documentation content needs to be created in Markdown.

  The trouble with CommonMark, the quasi-standard Markdown implementation, is that it does not meet many of the requirements listed below, and is not extensible. This is why I chose python-markdown as source content format for this project. It has several built-in extensions that extend Markdown syntax with features, it is easy to extend further with supported third-party extensions, and in a pinch, perhaps I could write my own extension in Python if an unsupported feature is a must-have.

• File transclusion (dynamically pulling the content of one file into another) needs to be supported.

• Image captions, and dynamic links to image captions need to be supported, much like in reStructuredText.

• Variables (e.g. for brand names, dates, or frequently recurring snippets of text or image) need to be supported.

• A test suite needs to be supported.

  Currently, Travis CI is only configured to deploy the automatically generated HTML files, but I am planning to run a spellchecker, a link checker, and style guide validation as part of the build.

• Footnotes need to be supported.

• Collapsible sections need to be supported.

• Syntax-highlighted code blocks that dynamically reference external files (nice to have: in external repositories) need to be supported.

• Tabbed code blocks that let the user switch between code snippets written in different programming languages need to be supported.

• Table cells with merged rows and/or columns need to be supported.

  I have chosen and made work the cell_row_span python-markdown extension locally. However, I haven't yet been able to integrate the extension with the Travis CI deployment. This feature is currently not supported, but fails relatively elegantly, that is, the tables are still displayed and styled, but cells do not span columns or rows.

• Linking to specific anchor points and/or headings, not only to files as a whole, is supported.

• Custom CSS styling of the output needs to be supported.

Try it for yourself

1. Fork this repository.

2. Set up GitHub Pages deployment for it.

3. Sign up for a free Travis CI account.

4. Set up a Personal Access Token (PAT) for yourself on GitHub.

5. Encrypt the PAT, and replace the secure key with your encrypted key in the .travis.yml file.

6. Trigger a build, and hack away at the markdown source as you like.