You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Szymon Janc 275c4e0d31 Make homepage more compliant with ASF recommendations 3 months ago
custom-theme Make homepage more compliant with ASF recommendations 3 months ago
docs Update download page with comments from announce list moderator 8 months ago
extras search results: disallow indexing of older doc versions so that they do not appear in search results before the latest docs 3 years ago
versions Update old versions' syntax 3 years ago
.editorconfig links to manuals for doc page header 6 years ago
.gitignore Auto-generate supported board list from BSP metadata 2 years ago
.mdlrc mldrc: remove MD005 4 years ago
Dockerfile Add dockerfile to build docs 3 years ago update the release/refresh process instructions 3 years ago Fix warning on deprecated usage of yaml.load 2 years ago Support running the deploy script on linux 4 years ago
mkdocs.yml Apache Mynewt 1.9.0 and Apache NimBLE 1.4.0 release 8 months ago
requirements.txt Update python requirements with upto date versions 8 months ago Update script for Python3 compat 2 years ago

This is the site documentation for the Apache Mynewt project. It is built using MkDocs.

This repo previously contained all documentation relating to Apache Mynewt. The project documentation now resides in the mynewt-documentation repo. Code specific documentation is found in various mynewt-* code specific repos. Archived versions of the project documentation for releases 1.3.0 and earlier are found under versions.


Clone the repo:

git clone
cd mynewt-site

Optional: it's a very good idea to use a virtualenv:

virtualenv venv
. venv/bin/activate

Install the requirements:

pip install -r requirements.txt

Submitting updates

  1. Fork the repo.
  2. Work on the master branch.
  3. Preview your changes using MkDocs.
  4. Submit a pull request.

Deploying the latest docs

NOTE: These instructions assume that your workspace has all the mynewt repos cloned under the same parent directory.

First follow the steps at mynewt-documentation

Most steps for releasing docs happen at the mynewt-documentation repo. Follow the instructions there first.

Merge all changes and update

  1. Merge pull requests to master on github.
  2. Switch to the master branch.
    • git checkout master
  3. While in master, do git pull --rebase origin master to pull the latest merged changes.

Cut a new versioned documentation set (if appropriate)

NOTE: Skip these steps if you are just refreshing the current documentation or site.

  1. Create a new stanza in mkdocs.yml to reflect the new version.
    • At present master is the latest version.
    • And that should probably not change.
  2. Add a new stanza in custom-theme/choose_doc_version.html for the new version.
  3. Add a link to docs/ for the new version.
  4. Add a Disallow section to extras/robots.txt for the new version so that these documents do not appear in search results before the latest docs.
  5. Commit these changes.


  1. Run: ./


  1. Run: ./
  2. Visit http://localhost:8000


  1. Run: ./ build
  2. This will leave you on the asf-site branch.
  3. Commit & push the changes.

The runtime-bot github user does a build every ~15 minutes and opens a Pull Request against the asf-site branch if there are any changes. It is recommended that the runtime-bot PRs are used to deploy changes to the site instead of PRs from individual contributors. The runtime-bot PRs give us repeatable builds using known versions of the build tools.

For the deployed site a version prefix is added to the URL for each mkdocs page. When developing there is no version prefix. If you want to link from a site page to a documentation page you should prefix the URL with /DOCSLINK/ so that the user is taken to the correct location when browsing in production.

  1. Grab a link checking tool like Integrity
  2. Run: ./ --test-build
  3. Run: ./
  4. Point the link checker at http://localhost:8000/