This guide shows you how to use this templater to create a Converged Cloud technical documentation site. But before you keep reading have a look at our beauty:

Custom landing page:

Documentation page:

Check out this documentation templater in action with its Markdown helpers, tools, and extensions at the following link.

⚠️ Attention: This release introduces significant changes that may impact your existing setup. Please review the Upgrade to V2 (Breaking Changes) section below for detailed instructions on how to update your project. This upgrade includes the removal of SAP-specific assets, updates to Docsy, and numerous improvements and bug fixes.

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/[email protected]

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/v2 => /Users/d063222/Documents/sap/cc/hugo-documentation-templater

go 1.20

require github.com/sapcc/hugo-documentation-templater/v2 v2.0.4 // indirect

To import the templater, add the necessary settings to the config.yaml file in the imports section:

baseURL: "http:https://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/v2
      disable: false

hugo 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 tidy

After 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: 0

Add to the config.yaml following setting to display the print link:

outputs:
  section:
    - HTML
    - print

To 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: 10

To 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: 5

To 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/"

1. Create a new file for your landing page content, e.g., landing-page-new-content.html, and save it in the partials folder.
2. This content will be automatically inserted between the <main> tags on the landing page.

<main>{{/* Your custom content here from the partial */}}</main>

3. Reference the new content file in your config.yaml configuration file:

params:
  # Specify the landing page content template
  landingPageContentTemplateName: "landing-page-new-content"

1. Create a file named custom-styles.scss in the assets/scss folder.
2. 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:

1. Save the Diagram:

   • Create your diagram in diagrams.net.
   • Save it in the .drawio format:
     • Go to File -> Save as.
     • Select Format: XML File (.drawio).

2. Push the File:

   • After creating your .drawio file, push it to the desired location in your repository.

3. 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]

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/

• Removed ccloud assets (SAP logo and releated assets)
• Upgraded to Docsy v0.10.0
• Stylesheets adapted to the new Docsy version which includes Bootstrap 5.3.3 and dark mode.
• Several bug fixes and improvements

First update the hugo version, clean the modules and remove the public folder:

brew upgrade hugo
hugo mod clean
hugo mod tidy
rm -rf public

Afterwards update the templater module version:

hugo mod get github.com/sapcc/hugo-documentation-templater/[email protected]

To add the SAP assets module install the module with the following command:

hugo mod get github.com/sapcc/[email protected]

You should see the following in your go.mod file:

require (
  github.com/sapcc/hugo-documentation-templater-sap-assets v1.0.2 // indirect
  github.com/sapcc/hugo-documentation-templater v2.0.4
)

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
    - path: github.com/sapcc/hugo-documentation-templater
      disable: false