/osm-docs

a docs page for open service mesh

Primary LanguageHTMLApache License 2.0Apache-2.0

Open Service Mesh Docs

📖 This section contains the OSM Docs

🚢 Also the website config to generate docs.openservicemesh.io

🔗 Looking for the main OSM website? Visit osm-www

Editing Content

docs.openservicemesh.io is a static site. The documentation content needs to be located at content/docs/.

The content served on https://docs.openservicemesh.io is served from the main branch of this repo. Most updates should be made only in main.

If it's necessary to change published release-specific docs, those changes should be made in the release-specific branch serving those docs. Once configured as described in Adding release-specific docs, PRs to that branch will auto-build just like PRs to main.

To ensure the docs content renders correctly in the theme, each page will need to have front matter metadata. Example front matter:

---
title: "Docs Home"
linkTitle: "Home"
description: "OSM Docs Home"
weight: 1
type: docs
---

Front Matter Notes:

  • inclusion of type: docs is important for the theme to properly index the site contents
  • the linkTitle attribute allows you to simplify the name as it appears in the left-side nav bar - ideally it should be short and clear - whereas the title can handle longform names for pages/documents.

Adding release-specific docs

Steps to add a release-specific version of the docs site:

  1. Create a release branch from main in your fork of this repo. Name this new branch after the released major and minor version, like release-v0.8.
  2. Push your newly-created release branch upstream to this repo on GitHub in order for the new branch to be usable by Netlify.
  3. List the new branch in the config.toml for all currently-displayed versions.
  4. Open an issue in this repo asking for the Netlify config to be created and the site update to be completed.
  5. Netlify will deploy the branch to a url like https://release-v0-8--osm-docs.netlify.app/. Use this to preview and test that this branch builds correctly.
  6. When published, the newly-added branch will function like https://release-v0-8.docs.openservicemesh.io/

Site Development

Notes

  • built with the Hugo static site generator
  • custom theme uses Docsy as a base, with Bootstrap as the underlying css framework and some OSM custom sass
  • deployed to Netlify via merges to main. (@flynnduism can grant additional access to account)
  • metrics tracked via Google Analytics

Install dependencies:

Run the site:

// install npm packages
yarn

// rebuild the site (to compile latest css/js)
hugo

// or serve the site for local dev
hugo serve

Deploying the site:

The site auto deploys the main branch via Netlify. Once pull requests are merged the changes will appear at docs.openservicemesh.io after a couple of minutes. Check the logs for details.

Netlify Status

hugo serve will run the site locally at localhost:1313