glennr / compose

A Hugo theme for documentation sites. It's inspired by https://forestry.io/docs/welcome/

Compose

Compose is a Hugo theme for documentation websites, inspired by forestry.io's docs page. The theme provides a simple navigation & structure.

Features

1. Docs
2. Gallery Support (via shortcode)
3. Native lazy loading of images

Installation

Install a recent release of the Hugo "extended" version; ideally versions >= 0.61.0. If you install from hugo releases page, download the _extended version, which supports sass.

Run your site with compose theme

You could go with the options right below.

Option 1 (my favorite)

This option enables you to load compose theme as a hugo module.

git clone https://github.com/onweru/compose/
cd compose/exampleSite/
hugo server

There's one drawback to this technique. Your site would always use the most up-to-date version of the theme. This might break your site if there are drastic changes that you don't like.

You can overcome that drawback by forking the repo instead and following the same approach. Be sure the edit the theme = ["github.com/onweru/compose"] from the config.toml file appropriately.

⚠️ If you choose Option 2 or Option 3 below, ensure you edit these lines in the config.toml file as advised on the comments

Option 2 (recommended)

Generate a new Hugo site and add this theme as a Git submodule inside your themes folder:

hugo new site yourSiteName
cd yourSiteName
git init
git submodule add https://github.com/onweru/compose/ themes/compose
cp -a themes/compose/exampleSite/* .

Then run

hugo server

Hurray!

Option 3 (Great for testing quickly)

You can run your site directly from the exampleSite. To do so, use the following commands:

git clone https://github.com/onweru/compose/
cd compose/exampleSite/
hugo server --themesDir ../..

Although, option 3 is great for quick testing, it is somewhat problematic when you want to update your theme. You would need to be careful not to overwrite your changes.

Once set, jump over to the config.toml file and start configuring your site.

ExampleSite

The exampleSite, as the theme's user guide.

This guide covers the necessary bits. As the project evolves, the userguide will get more comprehensive

You can use Hugo to generate and serve a local copy of the guide (also useful for testing local theme changes), making sure you have installed all the prerequisites listed above:

git clone --recurse-submodules --depth 1 https://github.com/onweru/compose.git
cd compose/exampleSite/
hugo server --themesDir ../..

Note that you need the themesDir flag when running Hugo because the site files are inside the theme repo.

How do I disable dark mode?

Under params add enableDarkMode = false to your config.toml file. If your site is based on the exampleSite, the value is already included; you only need to uncomment it.

The user will still have the option to activate dark mode, if they so wish

From the same creator

1. Clarity Theme
2. Newsroom Theme
3. Swift Theme

License

This theme is available under the MIT license.