Skip to content

index.md

Latest commit

 

History

History
140 lines (100 loc) · 3.75 KB

index.md

File metadata and controls

140 lines (100 loc) · 3.75 KB

mkdocs-deploy

About

mkdocs-deploy began as a drop-in replacement for mike. The main goal is to provide a deployment tool that is version aware and plugable, capable of deploying multiple versions side by side to any target website.

Basic Usage (Getting Started)

Start by configuring your project

Build your project with mkdocs.

mkdocs build

To deploy this site somewhere (let's say version 1.0 will live locally at /media/my_site/all_versions/1.0):

mkdocs-deploy deploy 1.0

You can give each version a name that might appear in your theme:

mkdocs-deploy deploy 1.0 "First Version"

You can add extra aliases. Eg: make 1.x forward to 1.0. Aliases can always be set to something different.

mkdocs-deploy set-alias 1.0 1.x

Aliases can be set implicitly every time you deploy a new version. Unless otherwise configured every deployment implicitly replaces the latest alias.

Setting up a new project

Configure mkdocs-deploy in your project. Then...

# Deploy your first version
mkdocs-deploy deploy "1.0"

# If make sure you have at least one "latest".
mkdocs-deploy set-alias 1.0 latest 

# Set the default version for your site. Setting it to alias means it will change when latest changes
mkdocs-deploy set-
  • Deploy your first version.
  • Set a latest version
  • Set a default version, in most cases this should be latest

Built in support for

Source for site versions

  • Reading sites from local filesystem: as zip, tar, or directory of files.

Target to maintain site

Redirect mechanisms

  • HTML file redirects
  • S3 redirects

Making your site Version aware.

Through mike compatibility

The Material is compatible with versioning by mkdocs-deploy

To enable your material themed mkdocs to understand mkdocs-deploy versioning add the following section to your mkdocs.yaml file.

extra:
  version:
    provider: mike

Mkdocs-deploy generates a mike compatible file which themese can use named versions.json. Looking something like this:

[
   {
      "version_id": "1.0", 
      "title": "1.0", 
      "aliases": ["latest"]
   }
]

Through mkdocs-deploy compatibility

mkdocs-deploy maintains a file deployments.json:

{
   "versions": {
      "1.0": {
         "title": "First Release"
      }
   }, 
   "aliases": {
      "latest": {
         "version_id": "1.0", 
         "redirect_mechanisms": ["html"]
      }
   }
}

Note that this may be extended in future but mkdocks-deploy will endevour to ensure at least these keys are present. The redirect_mechanisms available will depend on plugins installed and proboally should be ignored by theme developers.

If mike exists, why mkdocs-deploy?

mike is very good if you are looking for a simple too for deploying multiple versions of docs to github pages from the command line.

mkdocs-deploy was designed to fill in a few places where mike is weaker:

  • Easier to work with best-practice CI pipeline
    • Does not require working on two branches at the same time
    • Separates build from deployment / publishing
  • Better suited to maintaining sites other than Github Pages
  • (Future enhancement) Better suited to gitops
  • Plugable designed to allow better integration with other tools