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:

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.
Push your newly-created release branch upstream to this repo on GitHub in order for the new branch to be usable by Netlify.
List the new branch in the config.toml for all currently-displayed versions.
Open an issue in this repo asking for the Netlify config to be created and the site update to be completed.
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.
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:

Hugo installation guide
NPM packages are installed by running yarn. Install Yarn if you need to.

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.

hugo serve will run the site locally at localhost:1313

timmyreilly / osm-docs