Skip to content

Latest commit

 

History

History
110 lines (74 loc) · 3.83 KB

previewing-docs-locally.md

File metadata and controls

110 lines (74 loc) · 3.83 KB
Raw

Previewing the website locally

The Knative website uses Material for MkDocs to render documentation. You can choose to install MkDocs locally or use a Docker image.

Install Material for MkDocs locally

Material for MkDocs is Python based and uses pip to install most of its required packages, as well as the optional add-ons we use. pip comes pre-installed with Python so it's included in many operating systems (like macOS or Ubuntu) but if you don’t have Python, you can install it from the Python website.

For some (e.g. folks using RHEL), you might have to use pip3.

Install using pip

  1. Install Material for MkDocs by running:

    pip install mkdocs-material

    For more detailed instructions, see Material for MkDocs documentation

  2. Install the extensions to MkDocs needed for Knative by running:

    pip install mkdocs-material-extensions mkdocs-macros-plugin mkdocs-exclude mkdocs-awesome-pages-plugin mkdocs-redirects

Install using pip3

  1. Install Material for MkDocs by running:

    pip3 install mkdocs-material

    For more detailed instructions, see the Material for MkDocs documentation

  2. Install the extensions to MkDocs needed for Knative by running:

    pip3 install mkdocs-material-extensions mkdocs-macros-plugin mkdocs-exclude mkdocs-awesome-pages-plugin mkdocs-redirects

Use the Docker container

//TODO DOCKER CONTAINER EXTENSIONS

Setting up local preview

When using the local preview, anytime you change any file in your local copy of the /docs directory and hit save, the site automatically rebuilds to reflect your changes!

To preview the docs locally:

  1. After you have installed Material for MkDocs and all of the extensions, head over to the Knative docs GitHub repository and clone the repo.

  2. In your terminal, go to the directory of the cloned repo.

  3. Start the preview by running one of the following commands:

    • Local Preview

      mkdocs serve

    • Local Preview with Dirty Reload If you’re only changing a single page in the /docs/ folder that is not the homepage or nav.yml, adding the flag --dirtyreload makes the site rebuild super crazy insta-fast.

      mkdocs serve --dirtyreload

    When the preview has built, you'll see the following:

    ...
INFO    -  Documentation built in 13.54 seconds
[I 210519 10:47:10 server:335] Serving on http://127.0.0.1:8000
[I 210519 10:47:10 handlers:62] Start watching changes
[I 210519 10:47:10 handlers:64] Start detecting changes

  4. Open the local preview by accessing http://127.0.0.1:8000. You should see the site is built! 🎉

Setting Up "Public" Preview

If, for whatever reason, you want to share your work before submitting a PR (where Netlify generates a preview for you), you can deploy your changes as a Github Page by running the command:

mkdocs gh-deploy --force

Expected output:

INFO    -  Documentation built in 14.29 seconds
WARNING -  Version check skipped: No version specified in previous deployment.
INFO    -  Copying '/Users/omerbensaadon/Documents/GitHub/MergeConflictsResolve/docs/site' to 'gh-pages' branch and pushing to GitHub.
INFO    -  Your documentation should shortly be available at: https://<your-github-handle>.github.io/docs/

Where <your-github-handle> is your Github handle.

After a few moments, your changes should be available for public preview at the link provided by MkDocs. This means you can rapidly prototype and share your changes before making a PR!