Skip to content

For full documentation visit mkdocs.org.

MkDocs @IST Austria

Prior to using MkDocs, you've to make sure, your user account fulfills the following prerequisites.

Prerequisites

  • You need an ssh client to login to ssh [user]@login.ist.ac.at (user is short for your username)
  • You need to be logged in at least once to either (for syncing and editing your page):
  • seafile.ist.ac.at 1
  • git.ist.ac.at
  • You need to have the public_html website for your user enabled:
  • Login to login.ist.ac.at ( ssh [user]@login.ist.ac.at )
  • Set permissions and create needed ~/public_html folder:
chmod o+x $HOME
mkdir ~/public_html
chmod o+rx ~/public_html

If you create a file index.html in the folder ~/public_html you should be able to point your browser to your newly created personal homepage: https://pub.ist.ac.at/~user/

Install MkDocs

As MkDocs is not installed centrally, you've to install it for your useraccount. Please follow these few steps:

  • Login to ssh [user]@login.ist.ac.at
  • Install MkDocs ~/.local/bin/pip3 install mkdocs –user

Tip

You can check, which version is installed by executing: ~/.local/bin/mkdocs --version

MkDocs is now installed for your user.

Create your first project

This is according to the instructions at www.mkdocs.org.

user@login1:~$ ~/.local/bin/mkdocs new my-test-project
INFO    -  Creating project directory: my-test-project
INFO    -  Writing config file: my-test-project/mkdocs.yml
INFO    -  Writing initial docs: my-test-project/docs/index.md
user@login1:~$ cd my-test-project/

Edit mkdocs.yml and add the line: site_dir: /nfs/home/user/public_html/my-test-project, where "user" is your username. You could use: nano -w mkdocs.yml on the console to edit the file.

user@login1:~/my-test-project$ ~/.local/bin/mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /nfs/home/user/public_html/my-test-project

Now the page has been created, and can be viewed at: https://pub.ist.ac.at/~user/my-test.project

You can now add/edit files below ~/my-test-project/docs and rebuild anytime.

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

Project layout

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

Edit Markdown

If you need an editor to write Markdown files, and you're not happy with the built-in editors of either seafile.ist.ac.at or git.ist.ac.at, there a a few options out there, from which I can suggest Typora.

  1. More information about the ISTCloud is at wiki.ist.ac.at/index.php/ISTCloud ↩