Start a New Template

Introduction

This documentation website was built using the incredible Hextra Hugo Theme and the Hextra Starter Template. In this guide, we will create a reusable Sombra template from the Hextra Starter Template repository to automate the creation of powerful documentation websites.

Note: Always review the license of the projects you fork for creating templates to ensure compliance.

Fork the Project

Start by forking the Hextra Starter Template repository to your organization’s GitHub account. This will allow you to make any modifications while preserving the original repository.

Create the `.sombra` Directory

After forking the repository, create a .sombra directory in the root of your project. This directory will store all necessary configuration files for the Sombra template.

Inside the .sombra directory, create a default.yaml file. This file will contain the template definitions and metadata required by Sombra to generate new projects.

Example structure:

.
├── .sombra/
│   └── default.yaml

.sombra/: Directory to store the template definitions.

Creating `default.yaml`

The default.yaml file defines variables, patterns, and rules for transforming the project files into a template. Below is an example of a basic default.yaml configuration:

vars:
  - repository
  - title

patterns:
  - pattern: "*"
    abstract: true
    default:
      "imfing/hextra-starter-template": "{{ .repository }}"
      My Site: "{{ .title }}"
      Hextra Starter Template: "{{ .title }}"

  - pattern: "LICENSE"
    # Copy the original license to a different folder
    path:
      "/": "vendors"
    name:
      "LICENSE": "hextra-starter-template.LICENSE"
    verbatim: true

vars: Variables used throughout the template to enable customization.
patterns: Specifies how files should be transformed during the templating process. Each pattern contains a wildcard (pattern) to match files, along with specific transformation rules.

Adding More Files

Add the following files to your project to complete the template:

.
├── .devcontainer
│   └── devcontainer.json
├── .github
│   └── workflows
│       └── pages.yaml
├── .gitignore
├── .gitpod.yml
├── .vscode
│   └── extensions.json
├── LICENSE
├── README.md
├── content
│   ├── _index.md
│   ├── about.md
│   └── docs
│       ├── _index.md
│       ├── first-page.md
│       └── folder
│           ├── _index.md
│           └── leaf.md
├── go.mod
├── go.sum
├── hugo.yaml
└── netlify.toml

Below is an expanded default.yaml that includes the new files:

---
vars:
  - organization
  - repository
  - title
  - demo

patterns:
  - pattern: "*"
    abstract: true
    default:
      "imfing/hextra-starter-template": "{{ .repository }}"
      My Site: "{{ .title }}"
      Hextra Starter Template: "{{ .title }}"

  - pattern: "LICENSE"
    # Copy the original license to a different folder
    path:
      "/": "vendors"
    name:
      "LICENSE": "hextra-starter-template.LICENSE"
    verbatim: true

  # Specific replacements for README.md
  - pattern: "README.md"
    content:
      "https://imfing.github.io/hextra-starter-template/": "{{ .demo }}"

  # Specific handling for Hugo configuration
  - pattern: "hugo.yaml"
    content:
      "https://github.com/imfing": "{{ .organization }}"
  - pattern: "go.mod"

  # Apply to all markdown files in the content directory
  - pattern: "content/**/*.md"

  # Deployment configuration
  - pattern: "netlify.toml"

  # Development files
  - pattern: ".devcontainer/*"
  - pattern: ".github/**/*"
  - pattern: ".vscode/**/*"
  - pattern: ".gitignore"
  - pattern: ".gitpod.yml"

Create a Release

Sombra Engine requires templates to have semantic version tags for updates to target repositories. Ensure that you create a release in GitHub with a version tag, such as 0.1.0, to mark it as ready for use.

How to use

The full example can be found in our repository. You can fork it into your organization and create a new repository with the following sombra.yaml file:

templates:
  - name: your-org/hextra-starter-template
    vars:
      organization: https://your-org.com/  # Set your organization URL
      repository: your-org/docs            # Set your repository full name
      title: Welcome to my docs            # Define the website title
      demo:                                # Demo URL is you have it

Conclusion

Creating a Sombra template from scratch allows you to control how new projects are initialized. By following these steps—forking the Hextra Starter Template, defining your .sombra/default.yaml, and using YAML configurations—you can create dynamic and maintainable templates that fit the needs of your projects.

Best practices