This guide shows you how to use this templater to create a technical documentation site that already comes with a custom theme. Here's what the result looks like:
Custom landing page:
Documentation page:
Check out this documentation templater in action with its Markdown helpers, tools, and extensions at the following link.
Please see Upgrade to V3 for detailed instructions on how to upgrade your site to v3.
- Introduces support for BPMN diagrams. For more details, refer to the diagrams section.
- Removed deprecated code to maintain compatibility with Hugo versions v0.128 and higher.
- Ensured compatibility with the latest Hugo version.
- Upgraded Docsy to version v0.11.0.
- Fixed load of drawio diagrams when base URL is different of the root URL.
- The
Create documentation issuelink now includes the page source URL, which will be displayed in the description of the GitHub issue.
Please refer to the official Hugo documentation for more details on how to install Hugo in other operating systems.
Prerequisite: Golang
brew install golang
brew install hugo
To verify your new install:
hugo version
hugo new site my-docu-site
cd my-docu-site
You can convert your site into a Hugo module using the hugo mod init <module path> command.
hugo mod init github.com/sapcc/my-docu-site
The Go <module path> should resolve to a valid VCS (Version Control System) repository, such as Git, allowing others to use your site as a dependency. If your site's source code is not available in a public VCS repository, you can use a single word as the Go module path.
To add the templater (hugo-documentation-templater) module as a dependency, use the following command:
hugo mod get github.com/sapcc/hugo-documentation-templater/v3@v3.0.1
If you are developing this module locally, add the following configuration to your go.mod file to redirect to your local folder:
module github.com/me/my-docu-site
// just for local dev add this line (adjust to your folder location)!
replace github.com/sapcc/hugo-documentation-templater/v3 => /Users/d063222/Documents/sap/cc/hugo-documentation-templater
go 1.24
require github.com/sapcc/hugo-documentation-templater/v3 v3.0.1 // indirectTo import the templater, add the necessary settings to the config.yaml file in the imports section:
baseURL: "http://example.org/"
languageCode: "en-us"
title: "My New Doc Site"
params:
# change this url to the one of your project to enable 'View page source', 'Edit this page' and 'Create documentation issue' links on the right side navigation
github_repo: "https://github.com/sapcc/your-repo-pointing-to-the-documentation"
menu:
# uncomment this section to add custom links to the top navigation
# main:
# - identifier: "Github"
# name: "Github"
# pre: "<i class='fab fa-github'></i>"
# url: "https://github.com/sapcc/your-repo-pointing-to-the-documentation"
# weight: 0
module:
hugoVersion:
extended: true
min: 0.73.0
imports:
- path: github.com/sapcc/hugo-documentation-templater/v3
disable: falsehugo server --disableFastRender --ignoreCache
The --disableFastRender enables full re-renders on changes.
The --ignoreCache ignores the cache directory.
If you encounter any errors when starting the application, try running the following command to clean up the cache and remove unused modules:
hugo mod clean
hugo mod tidyAfter running the cleanup command, restart the Hugo server as described in the previous section. If you still encounter issues, try deleting the public folder and then restart the server.
Edit the name attribute on the Hugo config file config.yaml.
title: "My New Doc Site"Add a menu configuration similar to the following in the config.yaml (see Hugo documentation):
menu:
main:
- identifier: "Github"
name: "Github"
pre: "<i class='fab fa-github'></i>"
url: "https://github.com/sapcc/your-repo-pointing-to-the-documentation"
weight: 0Add to the config.yaml following setting to display the print link:
outputs:
section:
- HTML
- printTo customize the landing page, add a file named _index.md to the root of the content folder. These are available attributes you can use to customize the hero section:
---
heroTitle: "The best documentation ever"
heroSubtitle: "This is the subtitle of the hero section"
heroImage: "images/custom-hero-image.jpg"
heroButtonTitle: "Documentation"
heroButtonLink: "docs/customer"
---To display recent file changes in your documentation content as they are committed to GitHub, you just need to configure the number of changes to be shown. Add the following configuration to your config.yaml to activate this section:
params:
# number of file changes to be displayed in the landing page.
recentDocChanges: 10To display recent blog posts on the landing page as they are committed to GitHub, you need to activate this section by specifying the number of blog posts to show. Add the following configuration to your config.yaml file:
params:
# number of last blog posts to be displayed in the landing page.
recentBlogPosts: 5To enable a custom section index that allows users to jump to specific documentation sections from the landing page, add the landingSectionIndex: true parameter to the _index.md file of the desired section.
Example:
If you have an architecture folder with a section definition file located at content/docs/architecture/_index.md, you should include the landingSectionIndex: true parameter as shown below:
---
title: "Architecture"
linkTitle: "Architecture"
weight: 1
landingSectionIndex: true
description: >
Architecture overview
---A new entry will be added at the bottom of the landing page, featuring links and descriptions to help users navigate directly to the desired sections.
Here’s an improved version of the text along with the Markdown code:
Set up an overview section on the landing page by configuring the relevant settings. You can customize this section using the provided configuration options.
Configuration description:
params:
overviewSection: <[]Object>
label: <string>
icon: <string>
links: <[]Object>
- label: <string>
path: <string>Example:
params:
# overview section configuration
overviewSection:
- label: Compute
icon: "fa-server"
links:
- label: Servers
path: "/docs/customer/compute/virtual-servers/"
- label: "Block Storage"
path: "/docs/customer/compute/block-storage/"
- label: Networking
icon: "fa-wifi"
links:
- label: Jump Servers
path: "/docs/customer/networking/jump-servers/"
- label: "Load Balancer"
path: "/docs/customer/networking/load-balancers/"- Create a new file for your landing page content, e.g.,
landing-page-new-content.html, and save it in thepartialsfolder. - This content will be automatically inserted between the
<main>tags on the landing page.
<main>{{/* Your custom content here from the partial */}}</main>- Reference the new content file in your
config.yamlconfiguration file:
params:
# Specify the landing page content template
landingPageContentTemplateName: "landing-page-new-content"- Create a file named
custom-styles.scssin theassets/scssfolder. - Add your styles using the following example:
/* Example of defining variables in Sass and reading parameters from the config */
$heroImage: unquote(
'{{ default "images/Hero_background.jpg" .Params.heroImage }}'
);
/* Set up a new CSS class and use the variable in it */
.custom-jumbotron {
background: var(--color-global-bg) url($heroImage) top center no-repeat;
}To insert custom code (such as CSS imports, cookie consent scripts, or similar) into the head section of the landing page, include the landing-page-head-custom.html partial.
Simply organize your documentation into folders under content/docs/. Each folder should include a _index.md file with the following information:
---
title: "Main title of the section"
linkTitle: "Name on the side navigation"
weight: "integer number describing the position in the side bar"
description: >
"Some description useful"
---Search engine and field in the top navigation bar is setup per default. Search field on the right side navigation is per default disabled.
Original documentation: https://geekdocs.de/shortcodes/mermaid/
Live Editor to test diagrams: https://mermaid-js.github.io/mermaid-live-editor
```mermaid
sequenceDiagram
Alice->>Bob: Hello Bob, how are you?
alt is sick
Bob->>Alice: Not so good :(
else is well
Bob->>Alice: Feeling fresh like a daisy
end
opt Extra response
Bob->>Alice: Thanks for asking
end
```
To incorporate diagrams created with diagrams.net into your documentation, follow these steps:
-
Save the Diagram:
- Create your diagram in diagrams.net.
- Save it in the
.drawioformat:- Go to
File->Save as. - Select
Format: XML File (.drawio).
- Go to
-
Push the File:
- After creating your
.drawiofile, push it to the desired location in your repository.
- After creating your
-
Include the Diagram:
- To use the diagram in your document, include it with the absolute path as shown below:
{{</* diagramsnet file="source/help/diagram-drawio-example.drawio" */>}}
By following these steps, you can easily include and display your draw.io diagrams in your documentation. See example below:
Nomnoml is a tool for creating UML diagrams using a straightforward syntax. For more information, visit the Nomnoml website or check out the GitHub repository.
Example:
[Pirate|eyeCount: Int|raid();pillage()|
[beard]--[parrot]
[beard]-:>[foul mouth]
]
[<abstract>Marauder]<:--[Pirate]
[Pirate]- 0..7[mischief]
[jollyness]->[plunder]
[jollyness]->[rum]
[jollyness]->[singing]
[Pirate]-> *[rum|tastiness: Int|swig()]
[Pirate]->[singing]
[singing]<->[rum]
[<start>st]->[<state>plunder]
[plunder]->[<choice>more loot]
[more loot]->[st]
[more loot] no ->[<end>e]
[<actor>Sailor] - [<usecase>shiver me;timbers]
bpmn-js is a library for rendering and interacting with BPMN 2.0 diagrams directly in the browser. Further details can be found at https://bpmn.io/toolkit/bpmn-js/ or the GitHub repository.
Example:
{{< bpmn file="source/help/diagram-bpmn-example.bpmn" >}}
See further details on how to use BPMN diagrams in the diagrams section.
Based on Bootstrap 5.3.3
Creating a new package.json file https://docs.npmjs.com/creating-a-package-json-file
npm init
Install PostCSS so that the site build can create the final CSS assets https://github.com/google/docsy#prerequisites
npm install --save-dev autoprefixer
npm install --save-dev postcss-cli
https://www.dinofizzotti.com/blog/2017-05-01-adding-hugo-version-and-commit-information-to-a-status-page/ https://sizeof.cat/post/git-info-on-a-hugo-static-website/
- Update the hugo version:
brew upgrade hugo- Update the hugo-documentation-templater module version:
hugo mod get github.com/sapcc/hugo-documentation-templater/v3@v3.0.1- Update the
config.yamlfile to include the new module path and if not yet change the hugo version to 0.128.0:
...
module:
hugoVersion:
extended: true
min: 0.128.0
imports:
...
- path: github.com/sapcc/hugo-documentation-templater/v3
disable: false- Clean up the cache and remove unused modules:
hugo mod clean
hugo mod tidy
rm -rf publicTo add the SAP assets module install the module with the following command:
hugo mod get github.com/sapcc/hugo-documentation-templater-sap-assets@v1.0.2You should see the following in your go.mod file:
require (
github.com/sapcc/hugo-documentation-templater-sap-assets v1.0.2 // indirect
...
)
Remember that the sap-assets-module should be added in the first line in the config.yaml file:
...
module:
imports:
- path: github.com/sapcc/hugo-documentation-templater-sap-assets
disable: false
...