Edit

Docusaurus

It's possible to use mdoc with Docusaurus to build documentation websites. Several projects already use mdoc in combination with Docusaurus:

Requirements

  • yarn: to run docusaurus.

Installation

First, install the sbt-mdoc plugin using the normal mdoc installation instructions.

Next, enable the mdoc.DocusaurusPlugin in addition to the mdoc.MdocPlugin and define the moduleName setting to have your project name suffixed with -docs.

 // build.sbt
 lazy val docs = project
   .settings(
+    moduleName := "myproject-docs",
   )
-  .enablePlugins(MdocPlugin)
+  .enablePlugins(MdocPlugin, DocusaurusPlugin)
   .dependsOn(myproject)

Next, setup a normal Docusaurus site following the Docusaurus installation instructions.

Once you have a Docusaurus site setup, update siteConfig.js to point customDocsPath to the mdocOut directory with the generated mdoc output.

+ customDocsPath: "myproject-docs/target/mdoc",

Create static site

Generate a static website with docs/docusaurusCreateSite. This task runs several steps:

  • sbt docs/mdoc
  • cd website && yarn install && yarn run build
  • creates website/build/index.html that redirects to /myproject/
  • relativizes all links in the generated html so that it can be hosted on http://static.javadoc.io/

The static website gets generated in the website/build directory. You can copy these files over to any static HTTP server to host your website.

Publish to GitHub pages locally

If you have a GitHub repository with a gh-pages branch, update siteConfig.js to include the following information:

+  projectName: "mdoc",
+  organizationName: "scalameta",

Next, run docs/docusaurusPublishGhpages to publish the website to GitHub pages. This task run several steps:

  • sbt docs/mdoc
  • cd website && yarn install && USE_SSH=true yarn publish-gh-pages

Publish to GitHub pages from CI

You can configure your Travis CI server to publish docs after merge into master. The Docusaurus docs already have excellent instructions for how to set this up. If those instructions work for you, then that's great! No need to read this section here. However, you prefer to use "deploy keys" over "personal access tokens because deploy keys are limited to individual repositories instead of per-account. If this sounds interesting, read ahead.

Deploy key

Open the "Deploy key" menu in your project settings: https://github.com/scalameta/mdoc/settings/keys. Press "Add deploy key".

  • Title: use "Docusaurus Travis".

  • Allow write access: check the box, this is requires since we want to write to the gh-pages branch from CI.

  • Key: generate a fresh SSH key using ssh-keygen

    mkdir ~/.github
cd ~/.github
ssh-keygen -t rsa -b 4096 -C "olafurpg@gmail.com"
Enter file in which to save the key (/Users/ollie/.ssh/id_rsa): myproject
Enter passphrase (empty for no passphrase): <ENTER, NO PASSPHRASE>
Enter same passphrase again: <ENTER, NO PASSPHRASE>
Your identification has been saved in myproject.
Your public key has been saved in myproject.pub.

    It's important to use an empty passphrase so that the CI can install the key. Next, copy the public key and paste it into the GitHub "Key" field.

    # macOS
cat myproject.pub | pbcopy
# Linux
cat myproject.pub | xclip

Your screen should look like this

Add GitHub deploy key

Environment variables

Next open the Travis CI settings panel for your project: https://travis-ci.org/scalameta/mdoc/settings.

Add the following values:

  • GITHUB_DEPLOY_KEY: the base64 encoded secret key. Note, the secret key is the file without the .pub extension

    # macOS
cat myproject | base64 | pbcopy
# Ubuntu (assuming GNU base64)
cat myproject | base64 -w0 | xclip
# FreeBSD (assuming BSD base64)
cat myproject | base64 | xclip

.travis.yml

Next, update .travis.yml to trigger docs/docusaurusPublishGhpages on successful merge into master and on tag push. There are many ways to do this, but I recommend using Travis "build stages". It's not necessary to use build stages but they make it easy to avoid publishing the website multiple times from parallel jobs. Define the test and release build stages

stages:
  - name: test
  - name: release
    if: (branch = master AND type = push) OR (tag IS present)

Next, define your build matrix with docs/docusaurusPublishGhpages at the end

jobs:
  include:
    # stage="test" if no stage is specified
    - env: TEST="test"
      script: sbt test
    # release runs only if the previous stages passed
    - stage: release
      script: sbt docs/docusaurusPublishGhpages

For a complete example of the Travis configuration, see the .travis.yml in this project.

You're all set! Merge a PR to your project and watch the Travis job release the docs 😎

← Scala.js