Skip to content

Getting Started

Installing prerequisites

If you want to participate in development of this project, you need to carry out a couple of simple steps described below.

Clone the repository to your local machine.

Have the latest version of Python 3.6 installed, which can be downloaded from here.

Add the following two paths to your Windows Path user environment variable:

  • C:\Users\YourUserName\AppData\Local\Programs\Python\Python36-32
  • C:\Users\YourUserName\AppData\Local\Programs\Python\Python36-32\Scripts

Now, run any shell script (cmd, git-bash or PowerShell) and install/upgrade mkdocs and related packages:

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

Project Layout

1
2
3
4
5
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.

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.

FontAwesome

Up to Python 3.4?

Python versions above 3.4 are probably not supported yet. See the setup.py file for the classifiers section, it mentions Python versions up to 3.4.

Does not work on my website (yet)

FontAwesome Markdown does not work on this documentation website. I am trying to figure out why but so far no success.

FontAwesome 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.

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

Examples

This example uses 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. Right now version 0.2.5 is the latest but it doesn’t work out of the box. Instead, you have to install the latest version from the github repository. You can do that with the command below:

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

Deployment to GitHub Pages

Direct Deployment

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 your-github-login.github.io/mdocs.

Travis CI Deployment

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:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
sudo: false
language: python
python: '3.6'
install:
- pip install -U 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 --verbose --clean --strict
- 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.

References

Here are the most important links that have inspired me: