MkDocs for the Digital Archive

MkDocs is a static website generator for building project documentation written in Markdown. Markdown is a very simple markup language used to create formatted documentation (like you see on this page) in a plain text file without having to use a program like Microsoft Word. The combination of MkDocs and Markdown makes it possible for multiple authors to produce consistent looking documentation, keep it up to date, and make it accessible online.

Virtually all documentation about the Digital Archive is created and maintained using MkDocs. Some Digital Archive sites present information about their collection using either a sister WordPress website or the Omeka Simple Pages plugin.

About this MkDocs website

This MkDocs website is hosted at https://digitalarchive.us

The website's files and folders are maintained in the AvantLogic MkDocs repository.

MkDocs repository

Wherever this page refers to the MkDocs repository it means the location of the MKDocs working files and folders. That location is an AvantLogic Digital Archive Dropbox folder named \MkDocs\digital-archive. Additionally, these files are stored on GitHub at https://github.com/gsoules/MkDocs.

The navigation structure for the website is configured in the mydocs.yml file.

The website uses the Read the Docs theme for MkDocs.

Whenever you edit, add, move, or delete any of the MkDocs files, you must build and deploy the MkDocs website so that other people can see your changes.

Build the MkDocs website

To build the MkDocs website:

  • In Windows Explorer, navigate to the MkDocs repository
    Dropbox\Digital Archive AvantLogic\MkDocs\digital-archive
  • Open a Windows PowerShell or Git Bash window
  • Run the following command:
mkdocs build

mkdocs build

If you get the message Error: Config file 'mkdocs.yml' does not exist you are not in the digita-archive folder containing the mkdocs.yml file. CD to that folder.

The build updates the files in the site folder in the MkDocs repository with any changes made since the last build. You can now deploy these files to the server.

Also see the MkDocs documentation for building the website.

Deploy the MkDocs website

Use Beyond Compare to sync the site folder in the MkDocs repository with the corresponding folder on the server https://digitalarchive.avantlogic.net/docs. To learn how, see the Beyond Compare section in the instructions for installing a Digital Archive site.

Warning

Be very careful that the docs/protected/.htaccess file does not get removed during synchronization because it is necessary to support password protection. If the file gets deleted, replace it with the copy in Dropbox which is located in the protected folder in the MkDocs repository.

Writing documentation

MkDocs comes with a built-in dev-server that lets you preview your documentation as you work on it. To run the server:

  • In Windows Explorer, navigate to the MkDocs repository
    Dropbox\Digital Archive AvantLogic\MkDocs\digital-archive
  • Open a Windows PowerShell or Git Bash window
  • Run the following command:
mkdocs serve

mkdocs serve

If you get the message Error: Config file 'mkdocs.yml' does not exist you are not in the digita-archive folder containing the mkdocs.yml file. CD to that folder.

With the server running, you can now open http://127.0.0.1:8000 in your browser to see the default home page being displayed. When you edit a Markdown file and then save it, your changes automatically appear in the browser.

Editing and reviewing using the dev-server is much better than using a Markdown editor's preview window to see your changes That's because the dev-server displays the content exactly as it will appear when deployed on the server whereas an editor's preview pane will display its own flavor of Markdown of which there are many. However, if you need to edit Markdown and don't have access to the dev-server, using a Markdown editor is the next best way to go.

When you need to exit the server, type ctrl-C in the command window to return to the command prompt.

Edit an existing file

Follow these steps to edit an existing Markdown file:

Add a new file

Follow these steps to add a new page to the MkDocs website:

  • Create the new .mk file in the docs folder in the MkDocs repository
  • Add content written in Markdown
  • Edit the mkdocs.yml file in the MkDocs repository to add the file to the navigation hierarchy
  • Build the MkDocs website
  • Deploy the MkDocs website

Delete a new file

Follow these steps to remove a page from the MkDocs website:

See also the MkDocs documentation for Adding pages.