Documo docs

Thanks for buying a copy of Documo!

Please make sure you read through at least the installation instructions below to get your site set up.


Introduction to Documo

Documo is a theme built for hosting documentation in Ghost.

Using Ghost's brilliant writing and editing experience and publishing tools plus Documo for the layout, you can create flexible, beautiful, fast-loading documentation sites for your users or audience.

Documo comes with some key features for documentation sites like customisable navigation and search.

💬 If you have any questions, please email me or DM on Twitter.

⭐️ I offer Ghost hosting and concierge self-hosted installations.

Cheers!

  Dan Rowden

A brief overview of Documo

Buy Documo

Documo is priced at $49.

Special Offer: Every purchase of Documo comes with a $20 voucher for Cove, the commenting tool built into the theme. This is redeemable once you start a paid Cove plan ($5 or $10/month).

Looking for a Ghost host? A ghost site on Gloat costs $19/month or $189/year, with no limits on page views or members.

Buy Documo


Installation

Upload the theme ZIP

You can install the theme in Ghost by going to Settings > Design and clicking "Change theme" in the bottom left corner.

Then click "Upload theme" in the top right corner and select the Documo ZIP that you downloaded.

Upload the routes file

Go to Settings > Labs and upload the routes.yaml file from the theme ZIP.

Add your logo and icon (favicon)

Go to Settings > Design and upload your logo and favicon.

Add a home page

You need to create a home page for your site.

Create a new page with the slug /home/ and publish it.

This page can contain any content but it's probably useful to point new visitors to your main pages or sections.

Set up the menu

A two-level menu is supported in Documo.

Add links in Settings> Navigation like normal. To add a second level of links, add two hyphens and a space to the beginning of the label, like this:

The menu will look like this on your site:

You can also add section headings within your menu. Just add a # before any heading in the Navigation list, like this:

This will appear as a heading in the menu. Note: the link you've applied to this menu item will be removed.

Set up post collections

You can use Ghost's routes feature to add tags into post URLs, which helps create the appearance of groups of posts.

For example, if you had a group of posts about your API, you could tag these with API and then have api appear in those post's URLs:

By default, all posts and pages will have a URL like the second and third items in the list above (yourdomain.com/post-slug/)

To add tag slugs to post URLs, open routes.yaml in your theme's ZIP folder.

By default it looks like this:

routes:
  /:
    data: page.home
    template: home

collections:
  /:
    permalink: /{slug}/
    template: index

taxonomies:
  tag: /tag/{slug}/
  author: /author/{slug}/

Add a new section under collections like this:

collections:
  /:
    permalink: /{slug}/
    template: index
    filter: tag:-api
  /api/:
    permalink: /api/{slug}/
    filter: tag:api

This will add api to URLs of posts that are tagged with API.

Important: Note that you also have to filter out api posts from the base collection by adding the line filter: tag:-api.

You should add a new section for each group of posts. Remember to filter out each tag (you'll end up with something like tag:-api+tag:-secondtag


Buy Documo

Customisation

Change the accent colour

Your site's accent colour is used for links and some other highlighting across your site.

You can change this from the "Brand" section in Settings > Design.

Add a logo for dark mode

Documo has an automatic dark mode, which turns on when a user's device is in dark mode.

If your logo doesn't work in dark mode, you can upload a version of your logo specifically for dark mode in the "Site-wide" section in Settings > Design. This logo will be used when dark mode is enabled.

To enable search on your site, you need to create a new integration from Settings > Integrations, and copy the "Content API key" value. Then paste this into the "Search API key" setting in Settings > Design > Site-wide.

A search icon will appear on your site next to your logo.

The search will look across your post and pages, searching titles and content bodies for matching words.

Change which headings appear in a post's Table of Contents

By default, a post's h2, h3 and h4 headings will be shown in the floating Table of Contents.

If you want to change which headings you need to edit line 63 in post.hbs, which looks like this:

headingSelector: 'h2:not(.toc-exclude), h3:not(.toc-exclude), h4:not(.toc-exclude)',

If you only want h2 headings in your ToC, change the line to look like this:

headingSelector: 'h2:not(.toc-exclude)',

Note: the .toc-exclude CSS class is used to exclude specific headings from the ToC. For example, a heading like this:

<h2 class="toc-exclude">Heading</h2>

will not appear in the ToC.

Once you've made the change, make sure to ZIP the folder on your computer and re-upload it into Ghost.

Add comments to posts

You can add member-based commenting using the built-in Cove integration.

Once you've created a Cove account, simply go to Settings > Design and add your Cove site ID to the "Cove id" field. This will turn on comments on all posts.

For Cove to work, make sure you have Portal enabled, as it's used to sign up and sign in your visitors for them to be able to comment. You do not need to have the Portal button enabled.

Documo comes with a setting that makes all links to other sites open in new tabs.

To disable this, go to Settings > Design and turn off the "External links" option in the "Site-wide section" on the left.

Use a different Prism theme

Documo comes with a code syntax highlighter called Prism, using the Atom Dark theme.

If you want to use a different Prism theme, simply replace line 5 in partials/post-scripts.hbs with a link to the CSS file.

Here's a list of supported Prism themes.


Buy Documo

How to

How to remove the Table of Contents from a single post

There is a post template which does not include the table of contents. To use this on specific posts, open the sidebar when editing the post and select "Post No Toc" in the Template field.

How to add callouts

Use Ghost's blockquote to add notices and callouts into your docs.