This site is built using Hugo and the Docsy Theme.
- Start new development branches off of the
master
branch. - Create a pull request from your branch onto
master
. - Netlify will spawn a preview branch which will verify build success.
- Branches merged back into
master
will deploy to the current active version-branch of the site.
You can run the website locally using Hugo (Extended version).
- Hugo (Extended version); check the Hugo version specified in
netlify.toml
.
Before you start, install the dependencies. Clone the repository and navigate to the directory:
git clone https://github.com/spinnaker/spinnaker.io.git
cd spinnaker.io
The Spinnaker website uses the Docsy Hugo theme. Pull in the submodule and other development dependencies by running the following:
# pull in the Docsy submodule
git submodule update --init --recursive --depth 1
Make sure to install the Hugo extended version specified by the HUGO_VERSION
environment variable in the netlify.toml
file.
To build and test the site locally, run:
hugo server
This will start the local Hugo server on port 1313. Open up your browser to http:https://localhost:1313 to view the website. As you make changes to the source files, Hugo updates the website and forces a browser refresh.
At present, there is only one language in the ./content
directory. Docsy assumes lang-en and uses this language automatically, but you can add additional directories with different contents. There is also a langauge switcher in the navbar that can be enabled by adding that language to the [languages]
map in .config.toml
.
The Docsy theme is installed as a git submodule to this site. To update the theme, follow the Docsy documentation for git submodules. Make theme upgrades with care. Any changes to markup in the theme may render existing SCSS modifications ineffective.
Overrides to the theme are in ./layouts
, ./assets
, and ./static
. In order to continue to use Docsy's color variables, the entire theme SCSS collection is has been copied to ./assets
. Some of these SCSS files have been further modified to alter the appearance of various site components. If something "breaks" on upgrade, a good first step is to compare the previous markup for that component and make sure old SCSS selectors are still valid.
Dependencies are loaded into ./assets/scss
from ./themes/docsy
. If subsequent theme upgrades fail to load Bootstrap or Font Awesome assets, verify that the paths to these vendor dependencies within ./themes/docsy
are still valid.
title
: Displayed on the content page
linkTitle
: displayed where a link to the page appears (in the docs menu)
weight
: Determines the order of appearance in lists of content in the same directory, lowest first. To let all titles appear in alphabetical order, remove all weights.
description
: Short description, appears in lists of directory contents and on content page.
mermaid
: Boolean true
indicates that MermaidJS should be loaded on the page.
Mermaid is loaded into content pages only when the boolean frontmatter variable mermaid
is set to true
.
- Use the
mermaid
shortcode to make sure your graph isn't processed as markdown:
{{< mermaid >}}
graph TB
clouddriver(Clouddriver) --> clouddriver-caching(Clouddriver-Caching);
clouddriver --> clouddriver-rw(Clouddriver-RW);
clouddriver --> clouddriver-ro(Clouddriver-RO);
clouddriver --> clouddriver-ro-deck(Clouddriver-RO-Deck)
classDef default fill:#d8e8ec,stroke:#39546a;
linkStyle default stroke:#39546a,stroke-width:1px,fill:none;
classDef split fill:#42f4c2,stroke:#39546a;
class clouddriver-caching,clouddriver-ro,clouddriver-ro-deck,clouddriver-rw,echo-scheduler,echo-worker split
{{< /mermaid >}}
- Add the frontmatter variable to the page:
mermaid: true
.
The internal YouTube embed template provided by Hugo does not allow for the setting if height and width. A custom YouTube shortcode has been added to the repository to allow for the setting of height and width of YouTube videos embedded in Markdown content. Width and height should always include percent or unit of measure.
{{< customyoutube id="b7BmMY1kR10" width="320px" height="240px" >}}