Technical Information¶

Installing prerequisites¶

if you want to create your own project like this one, you need to have the latest version of Python 2.7 installed, which can be downloaded from here.

After that, install mkdocs and related packages:

1
2
3

pip install -U mkdocs mkdocs-material
pip install -U fontawesome-markdown
pip install -U pygments pymdown-extensions

Project Layout¶

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

Running the project in DEV¶

Open the command prompt in the project root directory and type:

1	mkdocs serve

Or, if you need to run it on a specific port, e.g. 8080, you can do one of the following:

1 2	mkdocs serve --dev-addr:8080 mkdocs serve -a :8080

Then open your browser and navigate to http://localhost:8000 or whatever port number you have configured.

Some Useful Commands¶

mkdocs new [dir-name] - Create a new project.
mkdocs serve - Start the live-reloading docs server.
mkdocs build - Build the documentation site.
mkdocs help - Print this help message.

Font Awesome¶

Font Awesome gives you scalable vector icons that can instantly be customized – size, color, drop shadow, and anything that can be done with the power of CSS. For more inpiration see these examples.

Font Awesome Markdown is a Markdown extension that looks for things like :fa-coffee: ( ) or :fa-beer: ( ) and replaces them with the Font Awesome icon markup.

Examples¶

This examples use the fontawesome_markdown extension:

1	What would you drink, :fa-coffee: or :fa-beer: ?

What would you drink, or ?

For this example, you must install the fontawesome_markdown extension with pip or install the latest version directly from the github repository:

1	pip install https://github.com/bmcorser/fontawesome-markdown/archive/master.zip

You may need to include -U in the above command if you already have this extension installed.

Then add the below to your mkdocs.yml file.

1 2	markdown_extensions: - fontawesome_markdown

In my case, this appeared to be not enough. I had to add the link to the Font Awesome stylesheet inside the main.html of my custom theme:

{% extends "base.html" %}

{% block styles %}
{{ super() }}
...
<link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.6.3/css/all.css" integrity="sha384-UHRtZLI+pbxtHCWp1t77Bi1L4ZtiqrqD80Kn4Z8NTSRyMA2Fd33n5dQ8lWUE00s/"
  crossorigin="anonymous">
{% endblock %}

Deployment¶

Deployment to GitHub Pages directly¶

To publish the project to GitHub Pages as a subdomain, e.g. /mdocs of the main website, you need first to create a repository with that name, e.g. mdocs and add it to your project as a remote.

Next make sure you have a gh-pages branch that exists. If it doesn’t:

1
2
3

git checkout -b gh-pages
git rm -rf .
git push --set-upstream origin gh-pages

Now, open the command prompt in the root directory (on the master branch) and type:

1	mkdocs gh-deploy

This will push the master branch to the remote gh-pages. After that, the project website is available at .

Deployment to GitHub pages via Travis CI¶

Go to your GitHub account and create a new Personal access token in your Developer settings. Copy the hash string.

Keep well the hash string!

You will see it only once when you create it.

In the Travis CI settings of your project add a new GITHUB_TOKEN environment variable with the value of the hash string your have just copied. Don’t forget to turn in ON and to ADD.

Configure the .travis.yml file. You may start with something like this:

sudo: false
language: python
python: '2.7'
install:
- pip install --upgrade pip
- pip install -r requirements.txt
- pip install https://github.com/bmcorser/fontawesome-markdown/archive/master.zip
script:
- git config credential.helper "store --file=.git/credentials"
- echo "https://${GITHUB_TOKEN}:@github.com" > .git/credentials
- mkdocs build
- if [ $TRAVIS_TEST_RESULT == 0 ]; then
    mkdocs gh-deploy --force;
  fi

The credentials here are necessary for the Travis agent to be able to connect to your Github repository and perform the necessary actions with it. Note that the credentials are based on the Personal access token you have created.

Also, I have put deployment inside the script fase instead of after_success as a workaround (see the tip of Chronial on this Travis issue #758). Otherwise, the batch succeeds with a successful build even if deploy fails after it.

Next, you need to have travis Rubygem installed on your local machine. If not, install it:

1	gem install travis

Using travis, add the encrypted token to .travis.yml:

1	travis encrypt GITHUB_TOKEN="the-token-from-github" --add

This will add the following block at the end of the file:

1
2
3

env:
  global:
  - secure: "lots-of-seemingly-random-characters"

Now, when you push your changes to the remote master, Travis CI should publish the compiled website to GitHub Pages if the build succeeds.