Exonum Documentation
This is the documentation repo for the Exonum platform. It contains source files used to build the documentation displayed on the Exonum website.
The Exonum documentation is written in Markdown, and uses mkdocs to generate HTML from sources. You can read about Markdown here or other places.
Contributing
In order to contribute, fork this repository, make some changes, and then submit them as a pull request. Simple!
Notice that the repository uses a set of linters to check possible problems with the contributed documents:
- markdownlint is used to lint Markdown files. Please see the rules list to fix possible problems with this linter
- html5validator is used for checking problems with the generated HTML pages
- linkchecker is used to find missing links
You can set up these tools locally (see the install
step in the Travis config
for more details) and run them using the ./misc/lint.sh
script with md
, html
,
links
, or all
arguments.
Page Meta
During the build process, mkdocs
gathers meta information for each page, which
is then used to provide page summary on social media, for search engines, etc.
The main meta information of interest is the page description. By default,
it is equal to the first paragraph of the page. You can override this default
by providing an explicit description on the very top of the page
with a front matter formatting:
---
description: 1-3 sentence description of the page
---
# Page Title
Page contents...
Similarly, you can redefine the displayed page title by providing a title
property
in the front matter. The site-wide “Exonum Documentation” suffix will be added
automatically.
Note. Although it looks like YAML front matter in Jekyll
and some other static site generators, mkdocs
actually uses a simpler parser
for the front matter. Be advised for possible discrepancies.
Build Instructions
It is a good idea to preview your changes locally before sending a pull request.
Installation
First, you need to install Python and python-pip.
Then, install the mkdocs
theme together with its dependencies:
pip install -r requirements.txt
You may use requirements.lock
instead of requirements.txt
in order to get repeatable builds.
To install linters, use
pip install -r dev-requirements.txt
markdownlint
needs to be installed separately, as it is written in Ruby and uses
gem
as the package manager.
Viewing Documents Locally
In order to run a local web server serving docs, use:
mkdocs serve
The web server will be available on 127.0.0.1:8000.
To generate HTML files from the Markdown source files, use:
mkdocs build
The generated pages will be available in the site/ directory.
License
Copyright 2017, Exonum Team
The Exonum documentation is licensed under the Creative Commons Non-Commercial Share-Alike International License (version 4.0). Code samples are licensed under the Apache License (version 2.0). See LICENSE and LICENSE-CODE for details.