tech-docs-template

Overview

The Tech Docs Template is a Middleman template that you can use to build technical documentation using a GOV.UK style.

Detected project type: Ruby.

This repository was migrated from upstream source github.com/shafiqalibhai/tech-docs-template and is preserved here for archival, reference, or continued local development.

At a glance

• Default branch: master
• Visibility: public
• Size: 1.1 MB
• Created: 2026-04-27
• Last updated: 2026-04-27
• Stars / Forks / Open issues: 0 / 0 / 0

Languages

Language	Bytes	Share
Ruby	4,385 bytes	58.0%
Shell	2,930 bytes	38.8%
SCSS	130 bytes	1.7%
HTML	82 bytes	1.1%
JavaScript	28 bytes	0.4%

Repository structure

• optional/
• screenshots/
• template/
• .editorconfig (593 B)
• .gitignore (433 B)
• .rspec (30 B)
• .travis.yml (63 B)
• create-test-site.sh (1,193 B)
• Gemfile (124 B)
• Gemfile.lock (2,887 B)
• LICENCE (1,111 B)
• README.md (5,088 B)
• Thorfile (3,840 B)

Getting started

Clone the repository:

git clone https://forgejo.deployview.com/ssa/tech-docs-template.git
cd tech-docs-template

Installation

bundle install

Usage

Refer to the source files in this repository for entry points and intended usage. Update this section with concrete examples once they are established.

Original README

The content below is preserved from the previous README. Headings have been demoted so they don't compete with the new top-level sections.

Tech Docs Template

The Tech Docs Template is a Middleman template that you can use to build technical documentation using a GOV.UK style.

This repo is the template used to generate new sites. The generated site uses HTML, CSS, JS and images from the tech docs gem.

You’re welcome to use the template even if your service isn’t considered part of GOV.UK, but your site or service must not:

• identify itself as being part of GOV.UK
• use the crown or GOV.UK logotype in the header
• use the GDS Transport typeface
• suggest that it’s an official UK government website if it’s not

👉 To find out more about setting up and managing content for a website using this template, see the Tech Docs Template documentation.

Before you start

To use the Tech Docs Template you need:

• Ruby
• Middleman

Get started

To create a new project using the Tech Docs Template, run:

middleman init PROJECT_NAME -T alphagov/tech-docs-template

where PROJECT_NAME is the name of your new project.

This command creates a minimal functional website using the Tech Docs Template.

Preview your website locally

To preview your new website locally, navigate to your project folder and run:

bundle exec middleman server

👉 See the generated website on http://localhost:4567 in your browser. Any content changes you make to your website will be updated in real time.

To shut down the Middleman instance running on your machine, use ctrl+C.

If you make changes to the config/tech-docs.yml configuration file, you need to restart Middleman to see the changes.

Configure your website

The middleman init command creates a minimal website with basic configuration.

You can change your website's configuration by editing the config/tech-docs.yml file.

👉 See what configuration options are available.

You can set page-specific options by editing the page's frontmatter.

👉 See how frontmatter configuration options are available.

Adding content

You can add content by editing the index.html.md.erb file. These files support content in:

• Markdown
• HTML
• Ruby

👉 For example, you can use Markdown and HTML to generate different content types and Ruby partials to manage content.

Any file in the source folder ending in .html.md.erb produces a separate page for your website.

👉 Learn more about producing more complex page structures for your website.

Publishing

To publish your website, you need to:

• build the HTML pages
• host your website
• decide how to push changes to your website

To build the HTML pages from content in your source folder, run:

bundle exec middleman build

Every time you run this command, the build folder gets generated from scratch. This means any changes to the build folder that are not part of the build command will get overwritten.

There are many options for hosting and pushing changes to your website, so it's worth considering user needs and constraints before making a choice.

Troubleshooting

Run bundle update to make sure you're using the most recent Ruby gem versions.

Run bundle exec middleman build --verbose to get detailed error messages to help with finding the problem.

Contribute

👉 See the CONTRIBUTE.md file in the tech-docs-gem repository.

Licence

Unless stated otherwise, the codebase is released under the MIT License. This covers both the codebase and any sample code in the documentation.

The documentation is © Crown copyright and available under the terms of the Open Government 3.0 licence.

Contributing

Contributions are welcome. The typical workflow is:

1. Open an issue describing the change you'd like to make.
2. Fork the repository (or create a feature branch if you have write access).
3. Commit your changes with clear, descriptive messages.
4. Open a pull request against the master branch.

Please follow the existing code style and include tests or reproduction steps where relevant.

License

No LICENSE file is currently present in this repository. Treat the contents as all rights reserved by the author until an explicit license is added. If you intend to share or accept contributions, consider adding an OSI-approved license such as MIT, Apache-2.0, or GPL-3.0.

Repository

• Browse: https://forgejo.deployview.com/ssa/tech-docs-template
• Clone (HTTPS): https://forgejo.deployview.com/ssa/tech-docs-template.git
• Clone (SSH): ssh://git@forgejo.deployview.com:30143/ssa/tech-docs-template.git
• Upstream / origin: github.com/shafiqalibhai/tech-docs-template

---

This README was generated automatically based on repository metadata, contents, and any prior README content. Edit any section above to add project-specific detail.