If you put a plain html file in a Jekyll site, it will be ignored, but if you add some Jekyll front matter to the top of your html as plain text, it will be included in the Jekyll site. Fortunately, Jekyll doesn't insist on having markdown as an input. It can use markdown as an input - and create html from it just as Jekyll does. So what I wanted was to pipe the doxygen output into my Jekyll site, but keep the Jekyll formatting, and generate a consistent nav bar that looked the same whether you were in the Doxygen-created automatic docs, or the static markdown-based site. Based on formatted comments, Doxygen creates html (and various other formats if desired) docs.
#Doxygen markdown output code#
The sites it generates are generally good-looking.īut most of my interesting stuff comes from the Simul source code - I use Doxygen to generate documentation from source. Jekyll will format it, and apply a theme if you have one. It will only be used if it has Jekyll Front Matter at the top, like so: So if you put a file in your repo called test.md, that becomes a page on your website called test.html. When compiled to html by Jekyll, becomes: Markdown is much simpler - it's plain text with a few conventions, for instance: While html is a text format, it's hard to write - you often want to use a specialized editor - but these end up filling your file with unnecessary cruft - repeated format tags and so on. While the site can take straight-up html files and reproduce them on the site, it also understands Markdown syntax. Gh-pages uses a system called Jekyll, which is also great. One great thing about gh-pages is that because you edit it locally, you can use something like Sublime Text to edit the files, which still, in 2015, is so much more responsive than editing online with all the latency that entails. You edit your files locally, push them to Github, and the site automatically updates.
Github Pages is a wonderful system for building a website.