The documentation infrastructure is built on the following stones:
- GirHub Flavoured Markdown (GFM)
- GitHub Pages
- the GH Pages theme jekyll-theme-minimal
- Table of contents (TOC) created using jekyll-toc
- Markdown linting rules:
- only one H1 header (page title)
- H2 headers are the first header level listed in the TOC
All keyboard-xxx and lang-xxx repositories (except private ones) have their
own online site as subsites of giellalt.github.io.
There are separate pages for keyboards and
language models with links directly to all subsite repos.
To update the online documentation, just save Markdown files in the docs/
folder of the repository, commit (and if using git: push),
and the updated documentation will be online within a minute.
All source code in the lang-XXX repositories containing
documentation markup will
be automatically parsed and the documentation extracted. The extracted
documentation will be automatically added to the site on the next svn commit/git push.
Source file types being scanned for documentation comments are:
- lexc
- twolc
- cg3
- pmscript
- xfscript
The top directories src/ and tools/, including all subdirs, are scanned.
Generated files of the above types are not scanned.
Beyond what is included in GFM, the GiellaLT documentation infrastructure also supports Mermaid through the use of a GitHub Action to convert Mermaid markup to SVG.
Mermaid support has [recently been added to GtiHub](https://github.blog/2022-02-14-include-diagrams-markdown-files-mermaid/), but the support does not include GtiHub Pages (not yet, at least). It does cover displaying Markdown source file views, README files, issues and discussion. By adding Mermaid support also to our GitHub Pages sites, there is parity between GH Pages and the rest of GitHub, and documents will render the same everywhere.pie title Formal languages used in GiellaLT
"LexC" : 3129
"Xfst regex" : 2374
"Xfst script" : 856
"TwolC" : 125
Based on counts of all files of the various types in all repositories in the GiellaLT infra.