The CodeCharta docs use Jekyll and the Minimal Mistakes (MM) Theme. The target of the docs are users (the ones that use the ccsh and the web version) and developers (the ones that maintain and extend CodeCharta). These audiences share similar concerns. As an example most users don't need to know how to write a new importer. They could benefit from the context view, however.
The generated docs can be viewed locally before being pushed to GitHub (see below). Please note that some files like the web version of CodeCharta are generated by release.yml
when the release pipeline runs.
- Install Ruby version 2.7.0 or above (check with
ruby -v
). Please be aware, that some OS come with an old Ruby version. Rubyenv did wonders for me (you can skip these steps if you use rbenv already or have some other way to acquire ruby):brew install rbenv
- Add
eval "$(rbenv init -)"
to the~/.bash_profile
,~/.bashrc
,~/.zshrc
etc. dependent on your shell OR execute- For Bash:
PATH="$HOME/.rbenv/bin:$PATH"
andeval "$(rbenv init -)"
- For Zsh:
export PATH="$HOME/.rbenv/bin:$PATH"
andeval "$(rbenv init - zsh)"
- For C-Shell:
setenv PATH $HOME/.rbenv/bin:$PATH
andeval 'rbenv init - csh'
- For Bash:
- Close terminal
- Make sure that
~/.rbenv/shims/ruby
appears before/usr/bin
in the PATH by runningecho $PATH
which ruby
should now point to~/.rbenv/shims/ruby
rbenv install -v 3.0.2
- OPTIONAL to create a
.ruby-version
ingh-pages
cd gh-pages
to go into the docs directoryrbenv local 3.0.2
ruby -v
should now be 3.0.2 for this directory- Ensure that the
uri
module is at version 0.13.0- Use
irb
to open the Ruby shell - Run
puts URI::VERSION
to check theuri
version - If an upgrade is needed, execute
gem install uri
- Use
bundle
to install all gemsgem install bundler:2.0.2
andbundle update --bundler
in case the bundler needs to be updated first
bundle exec jekyll serve
to build the site and make it available on a local server- Now browse to http://localhost:4000/codecharta/
- the path
/codecharta
is there because we addedbaseurl
to our_config.yml
- the path
GitHub uses Jekyll to render static site content for Github-Pages. Content in a top-level docs folder or in a branch gh-pages is automatically rendered.
GitHub does not support all Jekyll plugins however and only supports those it has whitelisted.
In case it's important the technical underpinnings of Jekyll and Minimal Mistakes are described in the Tech Chapter.
The assets/img/*.drawio.*
files can be opened directly with Draw.io. Download Draw.io, click on File->Open and select the image file. Yes you can open an image file directly. This is because we exported the image with a complete copy of the diagram in the meta-data: File->Export As->PNG then "Include copy of my diagram".
Jekyll is a static site renderer written in Ruby and most notably it is directly supported by GitHub. By default, it does not provide any look-and-feel for your sites. MM provides that theme (css, layouts, some js etc.) and also adds very nice things like search.
At first sight Jekyll is very simple. Basically "all" it does is copy files from your project structure to the generated folder called _site
. So if you place an index.html
in your project root, it'll also be in the root of _site
. What creates value is that Jekyll can also modify the files during the copy operation, provided we tell it to:
- either we place a file in a special Jekyll folder like
_pages
or_posts
- a custom collection folder like
_docs
- or we place special front matter header in the beginning of the file
The Front Matter Header in a html file:
---
title: Some Title
customVariable: Dave
---
<p>Hi {{customVariable}}</p>
In all cases the file is processed using the Liquid Template Engine which we can use to replace parts of the file with any variable that is available. Some variables like {{date}}
are predefined by Jekyll. But we can also define our own custom variables like {{customVariable}}
in the Front Matter Header or in the _config.yml
.
Besides defining global variables, the _config.yml
is also used to configure Jekyll and the MM Theme. It also contains some comments that explain what the variables do. To further understand what the variables do it's best to check out the Jekyll Configuration and the MM Configuration. Please note that changes to the _config.yml
won't be picked up by bundle exec jekyll serve
. You need to stop and restart that command.
- Available MM Layouts
- Create a MM Image Gallery
- Change the MM docs navigation list
- Auto-generate MM Table of Contents for a page
- Align text blocks with MM
- Make links standout more with MM buttons
- Place special MM Notice blocks around text
MM can be modified by copying files from MM directly and changing their content. Take a look at the files in _includes
.
Jekyll uses kramdown to parse Markdown. Please take a look at its qickref. Also, please use this format for internal links between markdown files: [visualization]({{site.docs_visualization}}/visualization)
. It has the benefit that the build will fail locally if a file cannot be found. A link to a section of a different page would look like this: [link text]({{site.baseurl}}{% link _docs/01-01-document.md %}#section)
.
netstat -vanp tcp | grep 4000
kill <pid>
mkdir -p <project>/docs
cd <project>
rbenv local 2.6.3
cd docs
jekyll new .
- Read Minimal Mistakes Quickstart
- Set the remote theme:
remote_theme: "mmistakes/minimal-mistakes"
- ???
- Profit