SEO on Doctave

SEO is important for making sure search engines can index your documentation. Doctave provides ways for you to ensure that your documentation is ready for Google and other search engines.

Sitemap

Doctave generates a sitemap.xml for all your documentation sites automatically. You can find it by going to the path /sitemap.xml for your documentation.

For example, if your documentation site has the URL my-docs.doctave.dev, you can see the sitemap under my-docs.doctave.dev/sitemap.xml.

Doctave includes all pages from any public version you have set for you site.

Private or password protected versions aren't listed in the sitemap.

You can submit this sitemap for example to Google's Search Console for your custom domain.

Title

The page title is the text you see in the top of your browser, usually in the tab for the page. Improving titles is an important way to improve your search engine rankings.

By default, Doctave takes the file name of your document, converts it into a human readable format to use for your page title. It also appends the site title from your doctave.yaml to the end of the title:

Example:

• Page title: API Docs
• Site title: Union Developer Portal
• Final HTML title: API Docs · Union Developer Portal

You can customize the page title for Markdown documents in the page's frontmatter. Say you have a page guides/docs/getting-started.md, and you wanted to set a custom title:

---
title: Getting Started With Your First Project
---

# Getting started

...

This would make your full HTML title:

Getting Started With Your First Project · Union Developer Portal

Description

You can set the SEO meta description for a page with the frontmatter:

---
meta:
  description: "The description for the page"
---

# Getting started
...

This will include the following HTML tag in the head of the page once deployed:

<meta name="description" content="The description for the page">

Search engines recommend you keep your descriptions between 140 and 160 characters.

Social Media Cards

Doctave will generate social media card previews for your links to your documentation that get displayed by chat tools and social media platforms.

The image is generated based on the title of the page, and the logo and main light mode color of your theme.

The description (the short blurb shown above the card in the screenshot) and title can be customised as shown above.

General best practices

You should keep in mind other general best practices for improving the SEO of your documentation sites.

Here are a few things to keep in mind:

• Make your headings descriptive
• Make your URLs descriptive (Doctave uses the document file path for URLs)
• Have one h1 heading near the top of the page
• Use h2 and h3 tags for subheadings
• Give your images alt texts: ![this is the alt text](/_assets/cat.jpg)