Video Walkthrough of a Change
Thank you for improving this site! This site is open source and the API maintainers welcome your contributions. Please reach out if you have any questions. Minor changes may be made directly in GitHub’s online editor wherever Edit appears at bottom-right.
Changes are published automatically by GitHub pages when merged to branch “main”. When sending a pull request it’s necessary to change the base repo to “netfoundry/mop-api-docs” to avoid sending the request to the upstream forked theme repo.
The content of this site lives in the top-level directory
/docs in the GitHub repo netfoundry/mop-api-docs. Most of the content is in
/docs/_pages/ with meaningful names. You can add or edit Kramdown (GitHub-flavored Markdown)
.markdown; or Liquid template
The theme lives in the top-level
/ in the same GitHub repo as the content: netfoundry/mop-api-docs. The repo is forked from Minimal Mistakes v4.19.2 which publishes an excellent quick-start guide. The idea is to override theme defaults in the content area
/docs in order to minimize changes to the upstream theme.
/_layouts/default.html and is available immediately in the local preview. Changes to the default, inherited theme files don’t become visible in the local preview until they’re merged to the main branch in the Git remote. Most changes should be overrides under
These steps provide a local preview server at http://localhost:4000/
clone the repo
git clone firstname.lastname@example.org:netfoundry/mop-api-docs.git
switch to the content area
/docsin the cloned working copy
docker-compose up --build preview
browse to http://localhost:4000/
- Be aware that search is not available in the local preview.
- Stop the preview container
- Focus the terminal where the container is running
- Send a
- Alternatively, you could
run the preview container in the background
docker-compose up --build --detach preview
and later stop the preview container
docker-compose down --remove-orphans
Things to Know
- Local changes to files in
/docswill be picked up immediately by Jekyll, except
/docs/_config.ymlwhich requires restarting the preview container.
- Optionally, before running the container, export your GitHub API token as
JEKYLL_GITHUB_TOKENand it will be made available to Jekyll for querying metadata from the GitHub API.
- fork the repo, unless you have access to main repo
- clone the repo
- make a change
- create a local branch
- commit your change
- push your commit to the remote
- create a pull request for your branch
- change the base repo to “netfoundry/mop-api-docs”
- submit your pull request
- monitor for build failures
- All merges to the main branch are automatically published by GitHub pages.
- Pushes to main will also trigger a Github Action. The Github Action:
- validates the changes with Jekyll
- updates the Algolia search index. A Github secret is named
ALGOLIA_API_KEYneeds to be set for the Algolia step to pass and is defined in the Netfoundry Github Organization.
- The GitHub repo has branch protections for main that require successful Github actions before allowing the merge as well as a PR approval from another user.
- The domain name developer.netfoundry.io is a
CNAMEresource record in the netfoundry.io hosted zone in Route53. The
RDATAof the record is the GitHub Pages sub-domain.
❯ dig +short -tCNAME developer.netfoundry.io. netfoundry.github.io.