docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material:5.1.0
In order to render and preview the site locally (without docker) you will need a few things to get started.
- You will need to install python and pip
- After python is installed, you'll need the following python dependencies:
pip install mkdocspip install mkdocs-material==5.1.0 - Once you have all the pre-reqs installed. You can simply run
mkdocs serveand view the rendered content locally and makes changes to your documentation and preview them in realtime with a browser open.
Publishing is now done by the jenkins pipeline. Once a PR is merged to master, the changes will be reflected on the documentation site.
When a new version of EdgeX is released, we version the docs as well. There are three steps to make this happen:
- Add the version to be added to the
versions.jsonfile. This file will populate the drop down in the site deployed at https://docs.edgexfoundry.org
[
{"version": "1.1", "title": "1.1-Fuji", "aliases": []},
{"version": "1.2", "title": "1.2-Geneva", "aliases": []}
{"version": "[new version number here]", "title": "[name that is visible in the drop down]", "aliases": []}
]- The value placed in
versionproperty in the json above MUST match the name of the folder that contains the versioned content in thegh-pagesbranch. This is specified by updating thesite_dir:property in themkdocs.ymlfile:
site_name: EdgeX Foundry Documentation
docs_dir: ./docs_src
site_dir: ./docs/1.2 #UPDATE THE VERSION NUMBER HERE TO MATCH WHATS IN THE VERSION.JSON
site_description: 'Documentation for use of EdgeX Foundry'
site_author: 'Michael Johanson'
site_url: 'https://edgexfoundry.github.io/edgex-docs/'
repo_url: 'https://github.com/edgexfoundry/edgex-go'
repo_name: 'edgex/edgex-go'
copyright: 'Copyright © 2020 EdgeX Foundry'
...Once this is done and merged, the build job will place content in the specified folder in the gh-pages branch.
- The last step, once everything is in place, is to update the site. The docs site is a statically hosted site on github pages from the
gh-pagesbranch. Normally we leave this branch alone as the build job will take care of updating it. However, versioning is a bit different.You'll need to do TWO things. Ideally this would be automated, but it is manual for now given it happens once per release.- You'll need to repeat step 1 against the
gh-pagesbranch. Think of it as master is dev andgh-pagesis prod. - You'll need to update the
index.htmlto redirect users to the current version:
- You'll need to repeat step 1 against the
<!DOCTYPE html>
<html>
<head>
<title>Redirecting</title>
<script>
window.location.replace("1.2"); //UPDATE ME
</script>
</head>
<body>
</body>
</html>