Skip to content

Publishing OSG Pages with MkDocs

The OSG uses MkDocs for site documentation and team-specific web pages (e.g. https://opensciencegrid.org/technology/). This document contains instructions for creating a new OSG area through GitHub and transitioning an existing MkDocs GitHub repository from Travis CI to GitHub Actions.

Creating New Pages

Need assistance?

If you need any assistance with setting up your GitHub repository, please reach out to help@opensciencegrid.org.

This document assumes that you are an administrator of the opensciencegrid GitHub organization. Before starting, make sure that you have the git and gem tools installed.

  1. Create a new public repository in the opensciencegrid organization (referred to as <REPO NAME> in the rest of this document)

    1. Check the box marked Initialize this repository with a README
  2. Identify the repository as using mkdocs:

    1. On the repository home page (i.e., https://github.com/opensciencegrid/<REPO NAME>), click the gear button in the top right (next to "About")
    2. In the topics field, add mkdocs
    3. Click the “Save Changes” button
  3. Clone the repository and cd into the directory:

    git clone https://github.com/opensciencegrid/<REPO NAME>.git
    cd <REPO NAME>
    
  4. Create a gh-pages branch in the GitHub repository:

    git push origin master:gh-pages
    
  5. Update the contents of README.md and populate the LICENSE file with a Creative Commons Attribution 4.0 license:

    wget https://creativecommons.org/licenses/by/4.0/legalcode.txt > LICENSE
    
  6. Create and encrypt the repository deploy key

    1. Generate the repository deploy key:

      ssh-keygen -t rsa -b 4096 -C "[email protected]" -f deploy-key -N ''
      
    2. Install the travis gem:

      gem install travis
      
    3. Login using your GitHub credentials:

      travis login --com
      
    4. Enable the repository in Travis:

      travis enable --com -r opensciencegrid/<REPO NAME>
      
    5. Encrypt the deploy key and temporarily save the output (you will need the hashes later for .travis.env):

      travis encrypt-file --com deploy-key
      
    6. Stage and commit your files:

      git add LICENSE README.md deploy-key.enc
      git commit -m "Prepare the repository for Travis-CI deployment"
      

      Danger

      Do NOT commit the unencrypted deploy-key!

    7. Add the contents of deploy-key.pub to your repository's list of deploy keys. Make sure to check Allow write access.

  7. Follow these instructions to add the doc-ci-scripts sub-module

Use the mkdocs-v1 branch of the doc-ci-scripts submodule.

  1. Create mkdocs.yml containing the following:

    site_name: <TITLE OF YOUR SITE>
    site_url: https://opensciencegrid.org/<REPO NAME>
    repo_name: https://github.com/opensciencegrid/<REPO NAME>
    theme:
      name: material
    
    nav:
      - Home: 'index.md'
    
    markdown_extensions:
      - admonition
      - codehilite:
          guess_lang: False
      - meta
      - toc:
          permalink: True
    
  2. Create a docs directory containing an index.md that will be your home page.

  3. Stage and commit these changes:

    git add mkdocs.yml docs/index.md
    git commit -m "Staging initial web page contents"
    
  4. Push local changes to the GitHub repository:

    git push origin master
    

    Your documents should be shortly available at https://www.opensciencegrid.org/<REPO NAME>

Creating an ITB Area

This section describes creating an ITB repository for a documentation area created in the previous section

  1. Create a new repository in the opensciencegrid organization and name it <REPO NAME>-itb. For example, an ITB area for the docs repository has a repository name of docs-itb. The ITB repository will be referred to as <ITB REPO NAME> in the rest of this document.

    1. Check the box marked Initialize this repository with a README
    2. Once created, add the mkdocs topic by clicking on the "Add topics" button
  2. Clone the repository and cd into the directory:

    git clone [email protected]:opensciencegrid/<ITB REPO NAME>
    cd <ITB REPO NAME>
    
  3. Create a gh-pages branch in the GitHub repository:

    git push origin master:gh-pages
    
  4. Update the contents of README.md

  5. In the non-ITB repository, create and encrypt the ITB repository deploy key

    1. cd into the non-ITB repository and generate the ITB deploy key

      cd <REPO NAME>
      ssh-keygen -t rsa -b 4096 -C "[email protected]" -f deploy-itb
      
    2. Install the travis gem:

      gem install travis
      
    3. Encrypt the deploy key:

      travis encrypt-file deploy-itb
      
    4. Update .travis.env with the appropriate ITB values

    5. Add and commit your files:

      git add .travis.env deploy-itb.enc
      git commit -m "Add ITB deployment"
      

      Danger

      Do NOT commit the unencrypted deploy-itb!

  6. Add deploy-itb.pub to the ITB repository's list of deploy keys. Make sure to check Allow write access.

  7. Still in the non-ITB repository, push your local changes to the GitHub repository

    git push origin master
    

    Your documents should be shortly available at https://www.opensciencegrid.org/<REPO NAME>

Transitioning to GitHub Actions

Need assistance?

If you need any assistance with transitioning your repository to GitHub actions, please reach out to help@opensciencegrid.org.

When originally developed, OSG MkDocs repositories were set up to automatically publish web page changes through Travis CI. But in November 2020, Travis CI changed their pricing model so we are moving the automatic publishing infrastructure to GitHub Actions and using this opportunity to also upgrade the version of MkDocs.

To ensure that your pages continue to be autmoatically published you will need to prepare your repository for the new version of MkDocs, disable Travis CI, and enable GitHub Actions.

Preparing the repository

Before upgrading, you must fix the following incompatibilities:

  • Rename the pages: section of mkdocs.yml to nav:. The section contents are identical; only the name is changing.

  • Update all of the links in the documents as follows:

    • Ensure links end in .md
    • Ensure links are document-relative, not site-relative

    For example, links should be of the form ../software/development-process.md instead of /software/development-process.

Previewing your pages with Docker

If you would like to ensure the correctness of your fixes, run the following command:

docker run -it -v ${PWD}/docs -p 8000:8000 squidfunk/mkdocs-material:6.1.4

After running this command, enter localhost:8000 in your browser to preview your pages. Saved changes made to .md files are automatically updated in your browser!

Disabling Travis CI

After you've prepared your repository for the transition, disable Travis CI by removing related files from it. Perform the following actions from the command-line:

  1. Create a fresh clone of the repository that is still using Travis CI:

    git clone https://github.com/opensciencegrid/<GIT REPOSITORY>
    

    Important

    For the rest of the steps in this documentation to work, you should create a new clone of the repository using the above command, even if you already have an existing copy!

  2. cd into the directory containing the repository (should be the same as <GIT REPOSITORY> by default)

  3. Remove all of the Travs CI related files:

    git rm ci
    git rm .travis.env deploy-key.enc .travis.yml
    
  4. Commit your changes:

    git commit -am "Disable Travis CI"
    
  5. Push your changes (you will be prompted for your GitHub credentials):

    git push origin master
    

Enabling GitHub Actions

The new method for validating and publishing OSG pages for a MkDocs repository can be enabled entirely through the GitHub web interface:

  1. Navigate to the opensciencegrid fork of the GitHub repository in your web browser, e.g. https://github.com/opensciencegrid/docs/

  2. Click on the Actions tab:

    Select the 'Actions' tab from your GitHub repository

  3. Find the Publish MkDocs static HTML workflow by the Open Science Grid and click the Set up this workflow button:

    Select the 'Publish MkDocs static HTML workflow

  4. Click on the Start commit drop-down button then click Commit new file:

    Commit the workflow

  5. Navigate to the Actions tab to verify your transition. If you see green check marks, your pages are now being published with GitHub Actions!

  6. (Optional) Enable the Validate MkDocs Static HTML workflow to check for broken links and markdown correctness of pull requests to the repository.

    1. Navigate to the Actions tab as before

    2. Click on the New Workflow button:

      Click the 'New workflow' button

    3. Find the Validate MkDocs static HTML workflow by the Open Science Grid and click Set up this workflow

    4. As before, click on the Start commit drop-down button then click Commit new file