Reference

FAQ

Q: Is it really free?

Yes — MIT licensed, for personal and commercial use. The Buy me a coffee button is optional support, never a paywall. Hide it by leaving buy_me_a_coffee.username empty; hide the footer credit with footer.show_credit: false.

Q: Does it work on GitHub Pages?

Yes. Use the GitHub Actions workflow in Deploying so you get Jekyll 4 and all three plugins. The classic “legacy” Pages build also works if you stick to its allowed plugin list.

Q: Can I have more than one docs section?

Yes. Add another collection in _config.yml, add it to search.collections, and add its pages to _data/navigation.yml under new groups.

Q: How do I change the font?

Add a <link> to _includes/head-custom.html and override --font-sans in a small custom stylesheet, or directly in _sass/docsteer/_tokens.scss.

Q: How do I build a FAQ page like this one?

Set layout: faq on any page and list the questions under a faq: key in its front matter, each with a q, an a and an optional section. Answers are Markdown, so code blocks and links work as usual. For a long list shared across pages, put the same structure in _data/faq.yml and point at it with faq_data: faq instead.

Q: The colours don't change when I edit `_config.yml`

Restart bundle exec jekyll serve — _config.yml is only read at startup. Also check you edited the value under the docsteer: key, not a stray top-level one.

Q: Dark mode flashes white on load

That means the inline script in _includes/head.html was removed or moved below the stylesheet. It must run before main.css loads.

Q: Search returns nothing

Confirm search.json is being generated (visit /search.json directly). Check search.collections lists your collection name. Very new pages need a rebuild.

Common questions about DocSteer.

Updated Sep 1, 2026 Edit this page

Short answers to what people ask most. Can’t find yours? Press / to search the whole site, or open an issue.

Licence and cost

Is it really free?

Yes — MIT licensed, for personal and commercial use. The Buy me a coffee button is optional support, never a paywall. Hide it by leaving buy_me_a_coffee.username empty; hide the footer credit with footer.show_credit: false.

Do I have to credit DocSteer?

Appreciated, not required. The footer credit is on by default because it is how the theme gets found — but footer.show_credit: false removes it and the MIT licence does not ask for anything more.

Setup and hosting

Does it work on GitHub Pages?

Yes. Use the GitHub Actions workflow in Deploying so you get Jekyll 4 and all three plugins. The classic “legacy” Pages build also works if you stick to its allowed plugin list.

Can I have more than one docs section?

Yes. Add another collection in _config.yml, add it to search.collections, and add its pages to _data/navigation.yml under new groups.

Customising

How do I change the font?

Add a <link> to _includes/head-custom.html and override --font-sans in a small custom stylesheet, or directly in _sass/docsteer/_tokens.scss.

How do I add a 7th colour skin?

See Colour skins → Add a seventh skin.

How do I build a FAQ page like this one?

Set layout: faq on any page and list the questions under a faq: key in its front matter, each with a q, an a and an optional section. Answers are Markdown, so code blocks and links work as usual.

For a long list shared across pages, put the same structure in _data/faq.yml and point at it with faq_data: faq instead.

Troubleshooting

The colours don’t change when I edit _config.yml

Restart bundle exec jekyll serve — _config.yml is only read at startup. Also check you edited the value under the docsteer: key, not a stray top-level one.

Dark mode flashes white on load

That means the inline script in _includes/head.html was removed or moved below the stylesheet. It must run before main.css loads.

Search returns nothing

Confirm search.json is being generated (visit /search.json directly).
Check search.collections lists your collection name.
Very new pages need a rebuild.

Something is broken — where do I report it?

Open an issue on the GitHub repository.

About the name

Why “DocSteer”, and how do I pronounce it?

/dɒkˈstɪə/ — dok-STEER, stress on the second syllable, rhyming with beer. Two syllables, not three.

The name is the job description: the sidebar, the search box and the table of contents are all there to steer a reader to the page they actually came for.

A steer is also a young ox. That was not the plan, but as a description of something that hauls a large pile of documentation around without complaining, it is hard to argue with. The full confession is on the home page.