Structure of this repository

Basically we follow jekyll and minimal-mistake our documentation sites are based on.

.
├── _data
│   ├── links
│   navigation.yml
│   excluded_titles.yml
│   external_links.yml
│   link_aliases.yml
│
├── _includes
│   ├── footer
│   ├── head
│   ...
│   └── search
│
├── _js
│   ├── custom
│   ├── plugins
│   ├── vendor
│   _main.js
│
├── _layouts
│
├── _plugins
│
├── _sass
│   └── minimal-mistakes
│
├── .github
│   └── workflows
│
├── _site
│
├── _tools
│
├── assets
│   ├── css
│   ├── images
│   └── js
│
├── doc
│   ├── _admin-guide
│   ├── _dev-guide
│   ├── _doc-guide
│   └── site-internal
│
_config.yml
Gemfile
LICENSE.*
README.md

Directories

  • _data
    Contains further _site generation input files for navigation, link generation, exclusion, etc.
    • links
      DO NOT USE!!!
      It lives only during jekyll generatig the _site data, excluded from git via .gitignore
      It is built based the content of the doc folder and contains files used for autolink/tooltip generation.

  • _includes
    This folder contains reusable and/or common html and liquid codes the final _site pages are using.

  • _js
    • custom
      To stay organized, please keep our custom js scripts in this folder.
    • plugins
    • vendor 3rd party js scripts used mainly by minimal-mistakes, but also keeps dependencies of our modifications as well.
    • lunr lunr is also a 3rd party dependency, it is now the default search engine, and we have a slighty modified version of its lunr-en.js

  • _layouts
    The main layout files the final _site pages are based on. Only the really used layouts are kept, all the other default minimal-mistakes layouts wre removed.

  • _sass
    The Jekyll Sass converter input files, container of all the styles related sheets, except the main sheet files.

  • _site
    DO NOT USE!!!
    This is the generated static _site content container, the content of this foler will be the final HTML site.
    Excluded from git via .gitignore \

  • _tools
    This folder contains our self-made helper tools.

  • .github
  • assets
    • css
      The _site main style sheet definition files which include the content of the _sass folder and serve as style sheet files for skinning as well.
      See comments in main.scss for more.
    • images
      The _site image files collector folder, please keep all the used images here, and try keep them organized mainly on their collection membership.
    • js
      DO NOT USE!!!
      It lives only during jekyll serving _site data, excluded from git via .gitignore
      It is built from the content of the _js folder
  • doc
    This folder contains the real content, the markdwon files, of a given documentation collection.

Files

  • _config.yml
    Our Jekyll configuration file
  • Gemfile
    Jekyll and minimal-mistake Ruby gem dependencies
  • LICENSE.*
    All the licence files of the modules the project uses
  • README.md
    The project GitHub repository landing page readme file
  • _data/navigation.yml
    The input yaml file of the left navigation sidebar, this is generated by the navgen tool (DO NOT EDIT, your edits will be overwritten!).
  • _data/excluded_titles.yml
    A list of sentences that will be excluded from the autolink/tooltip generation.
  • _data/external_links.yml
    Collector of all the external links we are referencing in our pages, please keep all none site cross links here.
  • _data/link_aliases.yml
    A link ID based collection of alias sentences that will produce the same autolink/tooltip.
  • .github/workflows/jekyll-gh-pages.yml
    The GitHub CI Action site builder Workflow file.
  • _js/main.min.js
    All of our separate js script files (that not embedded into HTML pages) packed into a min.js file, except lunr files, see bellow. (DO NOT EDIT, your edits will be overwritten!)
  • _js/lunr/lunr-en.js
    This is a bit modified version of the lunr script that actually generates the search result output, we use a simplfied search method, actually we reverted back from the minimal-mistakes version to the original, default one described in the lunr help.
  • _plugins/common_includes.rb
    A Jekyll pre_render pass plugin that inserts our common inlude files into each markdown page
  • _plugins/generate_links.rb
    A Jekyll post_render pass plugin that generates the input link files for autolink/tooltip.
  • _plugins/generate_tooltips.rb
    A Jekyll pre_render pass plugin that generates the autolink/tooltip HTML code based on link output files of generate_links.rb and our custom markdwon extension.
  • _plugins/liquify.rb
    A Jekyll liquid filter plugin that can force the evaluation of a liquid expression.
  • _tools/banner.js
    A js script that adds a DO NOT EDIT banner to a given script file.
  • _tools/linkcheck
    A shell script that checks the validity and availability of the link URLs in a given link file, usually in our external_links.yml
  • _tools/navgen
    A shell script that generates the input navigation.yml file of our left navigation sidebar from the page titles
  • _tools/pack
    A shell script that produces the packed main.min.js file.
  • _tools/package.json.in
    The input json template file of the pack tool.
  • _tools/serve
    A jekyll serve wrapper with multiple additional features.

Updated: