Skip to content

Latest commit

 

History

History
 
 

doc-site

README.md

Hyperledger FireFly Documentation Site

This directory is based on the Hyperledger documentation template. The template utilizes MkDocs (documentation at mkdocs.org) and the theme Material for MkDocs (documentation at Material for MkDocs). Material adds a number of extra features to MkDocs, and Hyperledger repositories can take advantage of the theme's Insiders capabilities.

Prerequisites

To test the documents and update the published site, the following tools are needed:

  • A Bash shell
  • git
  • Python 3
  • The Material for Mkdocs theme.
  • The Mike MkDocs plugin for publishing versions to gh-pages.
    • Not used locally, but referenced in the mkdocs.yml file and needed for deploying the site to gh-pages.

git

git can be installed locally, as described in the Install Git Guide from GitHub.

Python 3

Python 3 can be installed locally, as described in the Python Getting Started guide.

Virtual environment

It is recommended to install your Python dependencies in a virtual environment in case you have other conflicting Python installations on your machine. This also removes the need to install these packages globally on your computer.

cd doc-site
python3 -m venv venv
source venv/bin/activate

Mkdocs

The Mkdocs-related items can be installed locally, as described in the Material for Mkdocs installation instructions. The short, case-specific version of those instructions follow:

pip install -r requirements.txt

Verify Setup

To verify your setup, check that you can run mkdocs by running the command mkdocs --help to see the help text.

Useful MkDocs Commands

The commands you will usually use with mkdocs are:

  • mkdocs serve - Start the live-reloading docs server.
  • mkdocs build - Build the documentation site.
  • mkdocs -h - Print help message and exit.

Adding Content

The basic process for adding content to the site is:

  • Create a new markdown file under the docs folder
  • Add the new file to the table of contents (nav section in the mkdocs.yml file)

If you are using this as a template for creating your own documentation, please see the instructions for customization.

Repository layout

mkdocs.yml    # The configuration file.
docs/
    index.md  # The documentation homepage.
    ...       # Other markdown pages, images and other files.