For a live version of this documentation, see https://dutchblockchaincoalition.github.io/CompanyPassport
This repository contains the source code of the technical documentation for the Company Passport project.
The documentation is built using a static site generator (Jekyll) and hosted on GitHub Pages for better readability. You can make contributions to this documentation by forking the repository, making the changes and opening a PR. Once your the PR is accepted the site is automatically built and deployed. The Jekyll theme that is used is Bulma Clean Theme.
In order to preview the changes you make, you will need to install Jekyll. If you have Ruby and RubyGems installed, you can simply run gem install bundler jekyll
. Otherwise, please follow the Jekyll Installation Guide for your operating system. Once Jekyll is installed, you can install the dependencies for our site.
cd docs # this is the root of our documentation source
bundle install --gemfile Gemfile.dev
Once Jekyll is installed, you can run a local development server to preview the site by running the following command:
# in <ROOT>/docs
bundle exec --gemfile Gemfile.dev jekyll serve
TIP: If you use the Live Reload plugin in your editor, you can connect to the server by adding the
--livereload
parameter.
When the site is deployed, the url routing is generated based on the directory structure of the /docs
directory.
Some examples:
- The
/docs/index.md
file will be deployed athttps://dutchblockchaincoalition.github.io/CompanyPassport
- The
/docs/technical/index.md
file will be deployed athttps://dutchblockchaincoalition.github.io/CompanyPassport/technical
- The
/docs/technical/status-list.md
file will be deployed athttps://dutchblockchaincoalition.github.io/CompanyPassport/technical/status-list
To create a new page, simply create a new markdown file in the desired location. At the top of the document, add the following frontmatter to set the layout and title of your page.
---
layout: page
title: <the title of your page>
---
For more advanced configuration options, please see the frontmatter options for [Jekyll](https://jekyllrb.com/docs/front-matter/) and the [Bulma Clean Theme documentation].
The top navigation bar is configured in /docs/_data/navigation.yml
. Please see the documentation for additional info.
Images and other static assets that you want include into your documentation should be added to the /docs/assets
directory. All the files located in this directory are copied in the build process and will be included in the deployment. PlantUMl diagrams are built automatically and don't need to be generated manually. See the section on PlantUML diagrams for more info.
Although most of the documentation can be written using normal markdown, the format for linking is a little different. Using this format ensures that the file paths are set correctly during local development, as well as when the site is being deployed.
Let's say you want to include an image located in the /docs/assets/my_image.png
directory. Normally, you would do that by adding ![image name](relative-path-to-assets-dir)
to your markdown file. Instead of passing a relative file path, we can specify a relative path (with the /docs
directory as the root) and let Jekyll figure out the rest. So instead, you include the image by writing ![image name]({{'/assets/my_image.png' | relative_url}})
. By adding the relative_path
filter, Jekyll will prefix the file path with the correct base url.
NOTE: This formatting rule does not only apply to images, but to all internal site links.
If you want to link to a source file within this repository, you can do so by using the following custom variables:
{site.github_repo}
- will be substituted withhttps://github.com/DutchBlockchainCoalition/CompanyPassport
{site.assets_src}
- will be substituted withhttps://github.com/DutchBlockchainCoalition/CompanyPassport/blob/main/docs/assets
So let's say you want to link to a PlantUML source file located at /docs/assets/my_diagram.puml
, you can do so by formatting your link as such: `[view source file]({{ site.assets_src }}/my_diagram.puml)
PlantUML is a scripting language for creating software diagrams by writing code. This has various benefits, including simplified version management. Most markdown renderers have no native support for rendering PlantUML diagrams and rendering a diagram therefore usually requires the author to manually export the image. This can become quite tedious and lead to version mismatches between the diagram source code and rendered image. Luckily, GitHub Actions and Jekyll can help us out.
The site's current configuration allows you to add PlantUML diagrams in two ways:
- By inlining the diagram source code within your markdown file
- By defining and referencing a PlantUML source file
For small diagrams, you can embed the PlantUML source code directly into your markdown file as follows:
{% plantuml %}
@startuml
Bob -> Alice : hello
@enduml
{% endplantuml %}
It's recommended to use a separate source file for larger diagrams.
During the build process, all source files within the /docs/assets
directory that end with .puml
are compiled to an .svg
file. This means that order to include your diagram into your document, you will have to use the .svg
extension.
In order to display a diagram of which the source file is /docs/assets/my_diagram.puml
, you will need to reference it like this ![my diagram]({{'/assets/my_diagram.svg' | relative_url}})
(.svg
, not .puml
).
NOTE: Jekyll doesn't support this feature natively. When developing locally, the diagrams are generated by the
:post_build
hook in/docs/_plugins/generate_diagrams_hook.rb
. In CI however, this is not possible because GitHub Pages currently only allows a curated selection of plugins to be used. Therefore this is handled by a separate CI workflow action.