{"id":19096578,"url":"https://github.com/sapcc/hugo-documentation-templater","last_synced_at":"2026-01-16T10:57:45.538Z","repository":{"id":38193678,"uuid":"485773531","full_name":"sapcc/hugo-documentation-templater","owner":"sapcc","description":"Dokumentation skeleton build with Hugo and Docsy theme","archived":false,"fork":false,"pushed_at":"2024-10-25T10:23:23.000Z","size":2219,"stargazers_count":3,"open_issues_count":4,"forks_count":1,"subscribers_count":49,"default_branch":"main","last_synced_at":"2025-02-19T18:47:23.622Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"SCSS","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sapcc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-04-26T12:20:18.000Z","updated_at":"2024-10-25T10:20:13.000Z","dependencies_parsed_at":"2024-09-09T09:56:11.343Z","dependency_job_id":"80d2beb9-b3a3-4919-9627-50ae4301a96b","html_url":"https://github.com/sapcc/hugo-documentation-templater","commit_stats":null,"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sapcc%2Fhugo-documentation-templater","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sapcc%2Fhugo-documentation-templater/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sapcc%2Fhugo-documentation-templater/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sapcc%2Fhugo-documentation-templater/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sapcc","download_url":"https://codeload.github.com/sapcc/hugo-documentation-templater/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240149795,"owners_count":19755750,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-09T03:37:08.321Z","updated_at":"2026-01-16T10:57:45.519Z","avatar_url":"https://github.com/sapcc.png","language":"SCSS","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Welcome to the Hugo Documentation Templater\n\n[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)\n\nThis 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:\n\nCustom landing page:\n\n![landing page example](static/images/landing_page_example.png)\n\nDocumentation page:\n\n![Landing page example](static/images/documentation_page_example.png)\n\n## Live Example\n\nCheck out this documentation templater in action with its Markdown helpers, tools, and extensions at the following [link](https://sapcc.github.io/hugo-documentation-templater/).\n\n## 🚨 Major Upgrade to V3 🚨\n\n**⚠️ Attention:** This release requires **Hugo v0.128** or higher. Running it with an older version is not supported and will not work with v3. This release introduces support for BPMN diagrams and numerous improvements and bug fixes.\n\nPlease see [Upgrade to V3](#upgrade-to-v3) for detailed instructions on how to upgrade your site to v3.\n\n## Release Notes\n\n- Introduces support for BPMN diagrams. For more details, refer to the [diagrams section](https://sapcc.github.io/hugo-documentation-templater/docs/markdown-helpers/#diagrams).\n- Removed deprecated code to maintain compatibility with Hugo versions v0.128 and higher.\n- Ensured compatibility with the latest Hugo version.\n- Upgraded Docsy to version v0.11.0.\n- Fixed load of drawio diagrams when base URL is different of the root URL.\n- The `Create documentation issue` link now includes the page source URL, which will be displayed in the description of the GitHub issue.\n\n## Create a New Documentation Site from Scratch\n\n### Install Hugo Extended Version\n\nPlease refer to the official Hugo documentation for more details on [how to install Hugo in other operating systems](https://gohugo.io/installation).\n\nPrerequisite: Golang\n\n#### Mac Users\n\n```\nbrew install golang\nbrew install hugo\n```\n\nTo verify your new install:\n\n```\nhugo version\n```\n\n### Create a Hugo Site\n\n```\nhugo new site my-docu-site\ncd  my-docu-site\n```\n\n### Convert Your Site into a Hugo Module\n\nYou can convert your site into a Hugo module using the `hugo mod init \u003cmodule path\u003e` command.\n\n```\nhugo mod init github.com/sapcc/my-docu-site\n```\n\nThe Go `\u003cmodule path\u003e` 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.\n\n### Declare the `hugo-documentation-templater` Module as a Dependency for Your Site\n\nTo add the templater (`hugo-documentation-templater`) module as a dependency, use the following command:\n\n```\nhugo mod get github.com/sapcc/hugo-documentation-templater/v3@v3.1.0\n```\n\nIf you are developing this module locally, add the following configuration to your go.mod file to redirect to your local folder:\n\n```go.mod\nmodule github.com/me/my-docu-site\n\n// just for local dev add this line (adjust to your folder location)!\nreplace github.com/sapcc/hugo-documentation-templater/v3 =\u003e /Users/d063222/Documents/sap/cc/hugo-documentation-templater\n\ngo 1.24\n\nrequire github.com/sapcc/hugo-documentation-templater/v3 v3.1.0 // indirect\n```\n\n### Update the Hugo Config to Import the Templater\n\nTo import the templater, add the necessary settings to the `config.yaml` file in the `imports` section:\n\n```yaml\nbaseURL: \"http://example.org/\"\nlanguageCode: \"en-us\"\ntitle: \"My New Doc Site\"\n\nparams:\n  # 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\n  github_repo: \"https://github.com/sapcc/your-repo-pointing-to-the-documentation\"\n\nmenu:\n  # uncomment this section to add custom links to the top navigation\n  # main:\n  #   - identifier: \"Github\"\n  #     name: \"Github\"\n  #     pre: \"\u003ci class='fab fa-github'\u003e\u003c/i\u003e\"\n  #     url: \"https://github.com/sapcc/your-repo-pointing-to-the-documentation\"\n  #     weight: 0\n\nmodule:\n  hugoVersion:\n    extended: true\n    min: 0.73.0\n  imports:\n    - path: github.com/sapcc/hugo-documentation-templater/v3\n      disable: false\n```\n\n### Start Hugo Server\n\n```\nhugo server --disableFastRender --ignoreCache\n```\n\nThe `--disableFastRender` enables full re-renders on changes.\nThe `--ignoreCache` ignores the cache directory.\n\n### Troubleshooting Application Start Errors\n\nIf you encounter any errors when starting the application, try running the following command to clean up the cache and remove unused modules:\n\n```bash\nhugo mod clean\nhugo mod tidy\n```\n\nAfter 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.\n\n## Content and Customization\n\n### Site Name\n\nEdit the name attribute on the Hugo config file `config.yaml`.\n\n```yaml\ntitle: \"My New Doc Site\"\n```\n\n### Add Non-content Entries to a Menu\n\nAdd a menu configuration similar to the following in the `config.yaml` (see [Hugo documentation](https://gohugo.io/content-management/menus/)):\n\n```yaml\nmenu:\n  main:\n    - identifier: \"Github\"\n      name: \"Github\"\n      pre: \"\u003ci class='fab fa-github'\u003e\u003c/i\u003e\"\n      url: \"https://github.com/sapcc/your-repo-pointing-to-the-documentation\"\n      weight: 0\n```\n\n### Print Option\n\nAdd to the `config.yaml` following setting to display the print link:\n\n```yaml\noutputs:\n  section:\n    - HTML\n    - print\n```\n\n### Landing Page\n\n#### Customize Hero Section\n\n### Customizing the Landing Page\n\nTo 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:\n\n```markdown\n---\nheroTitle: \"The best documentation ever\"\nheroSubtitle: \"This is the subtitle of the hero section\"\nheroImage: \"images/custom-hero-image.jpg\"\nheroButtonTitle: \"Documentation\"\nheroButtonLink: \"docs/customer\"\n---\n```\n\n#### Configure the Latest Changes Section on the Landing Page\n\nTo 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:\n\n```yaml\nparams:\n  # number of file changes to be displayed in the landing page.\n  recentDocChanges: 10\n```\n\n#### Configure the News Section on the Landing Page\n\nTo 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:\n\n```yaml\nparams:\n  # number of last blog posts to be displayed in the landing page.\n  recentBlogPosts: 5\n```\n\n#### Add a Custom Section Index for Navigation\n\nTo 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.\n\nExample:\n\nIf 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:\n\n```markdown\n---\ntitle: \"Architecture\"\nlinkTitle: \"Architecture\"\nweight: 1\nlandingSectionIndex: true\ndescription: \u003e\n  Architecture overview\n---\n```\n\nA 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.\n\nHere’s an improved version of the text along with the Markdown code:\n\n#### Configure an Overview Section for the Landing Page\n\nSet up an overview section on the landing page by configuring the relevant settings. You can customize this section using the provided configuration options.\n\nConfiguration description:\n\n```yaml\nparams:\n  overviewSection: \u003c[]Object\u003e\n    label: \u003cstring\u003e\n    icon: \u003cstring\u003e\n    links: \u003c[]Object\u003e\n      - label: \u003cstring\u003e\n        path: \u003cstring\u003e\n```\n\nExample:\n\n```yaml\nparams:\n  # overview section configuration\n  overviewSection:\n    - label: Compute\n      icon: \"fa-server\"\n      links:\n        - label: Servers\n          path: \"/docs/customer/compute/virtual-servers/\"\n        - label: \"Block Storage\"\n          path: \"/docs/customer/compute/block-storage/\"\n    - label: Networking\n      icon: \"fa-wifi\"\n      links:\n        - label: Jump Servers\n          path: \"/docs/customer/networking/jump-servers/\"\n        - label: \"Load Balancer\"\n          path: \"/docs/customer/networking/load-balancers/\"\n```\n\n#### Create a Custom Landing Page Content Template\n\n1. Create a new file for your landing page content, e.g., `landing-page-new-content.html`, and save it in the `partials` folder.\n2. This content will be automatically inserted between the `\u003cmain\u003e` tags on the landing page.\n\n```html\n\u003cmain\u003e{{/* Your custom content here from the partial */}}\u003c/main\u003e\n```\n\n3. Reference the new content file in your `config.yaml` configuration file:\n\n```yaml\nparams:\n  # Specify the landing page content template\n  landingPageContentTemplateName: \"landing-page-new-content\"\n```\n\n#### Style Your Custom Landing Page\n\n1. Create a file named `custom-styles.scss` in the `assets/scss` folder.\n2. Add your styles using the following example:\n\n```css\n/* Example of defining variables in Sass and reading parameters from the config */\n$heroImage: unquote(\n  '{{ default \"images/Hero_background.jpg\" .Params.heroImage }}'\n);\n\n/* Set up a new CSS class and use the variable in it */\n.custom-jumbotron {\n  background: var(--color-global-bg) url($heroImage) top center no-repeat;\n}\n```\n\n#### Adding Custom Code to the Head Section\n\nTo 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.\n\n### Documentation\n\n#### Content\n\nSimply organize your documentation into folders under `content/docs/`. Each folder should include a `_index.md` file with the following information:\n\n```markdown\n---\ntitle: \"Main title of the section\"\nlinkTitle: \"Name on the side navigation\"\nweight: \"integer number describing the position in the side bar\"\ndescription: \u003e\n  \"Some description useful\"\n---\n```\n\n#### Search\n\nSearch engine and field in the top navigation bar is setup per default. Search field on the right side navigation is per default disabled.\n\n#### Diagram Mermaid\n\nOriginal documentation: \u003chttps://geekdocs.de/shortcodes/mermaid/\u003e\n\nLive Editor to test diagrams: \u003chttps://mermaid-js.github.io/mermaid-live-editor\u003e\n\n````tpl\n```mermaid\nsequenceDiagram\n    Alice-\u003e\u003eBob: Hello Bob, how are you?\n    alt is sick\n        Bob-\u003e\u003eAlice: Not so good :(\n    else is well\n        Bob-\u003e\u003eAlice: Feeling fresh like a daisy\n    end\n    opt Extra response\n        Bob-\u003e\u003eAlice: Thanks for asking\n    end\n```\n````\n\n\u003cimg src=\"https://github.com/sapcc/hugo-documentation-templater/blob/main/static/images/ex_mermaid.png\"  width=\"500\"\u003e\n\n#### Using Diagrams from diagrams.net (previously draw.io)\n\nTo incorporate diagrams created with [diagrams.net](https://www.drawio.com/) into your documentation, follow these steps:\n\n1. **Save the Diagram**:\n\n   - Create your diagram in [diagrams.net](https://www.drawio.com/).\n   - Save it in the `.drawio` format:\n     - Go to `File` -\u003e `Save as`.\n     - Select `Format: XML File (.drawio)`.\n\n2. **Push the File**:\n\n   - After creating your `.drawio` file, push it to the desired location in your repository.\n\n3. **Include the Diagram**:\n\n   - To use the diagram in your document, include it with the absolute path as shown below:\n\n   ```tpl\n   {{\u003c/* diagramsnet file=\"source/help/diagram-drawio-example.drawio\" */\u003e}}\n   ```\n\nBy following these steps, you can easily include and display your `draw.io` diagrams in your documentation. See example below:\n\n\u003cimg src=\"https://github.com/sapcc/hugo-documentation-templater/blob/main/static/images/ex_draw_io_diagrams_net.png\"  width=\"500\"\u003e\n\n#### Diagram Nomnoml\n\nNomnoml is a tool for creating UML diagrams using a straightforward syntax. For more information, visit the [Nomnoml website](https://www.nomnoml.com/) or check out the [GitHub repository](https://github.com/skanaar/nomnoml).\n\nExample:\n\n```nomnoml\n[Pirate|eyeCount: Int|raid();pillage()|\n [beard]--[parrot]\n [beard]-:\u003e[foul mouth]\n]\n[\u003cabstract\u003eMarauder]\u003c:--[Pirate]\n[Pirate]- 0..7[mischief]\n[jollyness]-\u003e[plunder]\n[jollyness]-\u003e[rum]\n[jollyness]-\u003e[singing]\n[Pirate]-\u003e *[rum|tastiness: Int|swig()]\n[Pirate]-\u003e[singing]\n[singing]\u003c-\u003e[rum]\n[\u003cstart\u003est]-\u003e[\u003cstate\u003eplunder]\n[plunder]-\u003e[\u003cchoice\u003emore loot]\n[more loot]-\u003e[st]\n[more loot] no -\u003e[\u003cend\u003ee]\n[\u003cactor\u003eSailor] - [\u003cusecase\u003eshiver me;timbers]\n```\n\n\u003cimg src=\"https://github.com/sapcc/hugo-documentation-templater/blob/main/static/images/ex_nomnoml.png\"  width=\"500\"\u003e\n\n#### BPMN\n\n`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.\n\nExample:\n\n```bpmn\n{{\u003c bpmn path=\"source/help/diagram-bpmn-example.bpmn\" \u003e}}\n```\n\n\u003cimg src=\"https://github.com/sapcc/hugo-documentation-templater/blob/main/static/images/ex_bpmn.png\"  width=\"500\"\u003e\n\nSee further details on how to use BPMN diagrams in the [diagrams section](https://sapcc.github.io/hugo-documentation-templater/docs/markdown-helpers/#diagrams).\n\n## Extra Information\n\n### Bootstrap Version\n\nBased on Bootstrap 5.3.3\n\n### Build Assets\n\nCreating a new package.json file\nhttps://docs.npmjs.com/creating-a-package-json-file\n\n```\n\nnpm init\n\n```\n\nInstall PostCSS so that the site build can create the final CSS assets\nhttps://github.com/google/docsy#prerequisites\n\n```\n\nnpm install --save-dev autoprefixer\nnpm install --save-dev postcss-cli\n\n```\n\n### Git Information\n\nhttps://www.dinofizzotti.com/blog/2017-05-01-adding-hugo-version-and-commit-information-to-a-status-page/\nhttps://sizeof.cat/post/git-info-on-a-hugo-static-website/\n\n### Upgrade to V3\n\n1. Update the hugo version:\n\n```bash\nbrew upgrade hugo\n```\n\n2. Update the hugo-documentation-templater module version:\n\n```bash\nhugo mod get github.com/sapcc/hugo-documentation-templater/v3@v3.1.0\n```\n\n3. Update the `config.yaml` file to include the new module path and if not yet change the hugo version to 0.128.0:\n\n```yaml\n...\nmodule:\n  hugoVersion:\n    extended: true\n    min: 0.128.0\n  imports:\n  ...\n    - path: github.com/sapcc/hugo-documentation-templater/v3\n      disable: false\n```\n\n4. Clean up the cache and remove unused modules:\n\n```bash\nhugo mod clean\nhugo mod tidy\nrm -rf public\n```\n\n#### SAP Assets Module\n\nTo add the SAP assets module install the module with the following command:\n\n```bash\nhugo mod get github.com/sapcc/hugo-documentation-templater-sap-assets@v1.0.2\n```\n\nYou should see the following in your go.mod file:\n\n```\nrequire (\n  github.com/sapcc/hugo-documentation-templater-sap-assets v1.0.2 // indirect\n  ...\n)\n```\n\n**Remember that the sap-assets-module should be added in the first line in the config.yaml file:**\n\n```yaml\n...\nmodule:\n  imports:\n    - path: github.com/sapcc/hugo-documentation-templater-sap-assets\n      disable: false\n    ...\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsapcc%2Fhugo-documentation-templater","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsapcc%2Fhugo-documentation-templater","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsapcc%2Fhugo-documentation-templater/lists"}