Home SEO Optimization

SEO Optimization Guide

Search Engine Optimization (SEO) is crucial for ensuring that your documentation is easily discoverable by users searching for solutions online. SmartGen Docs provides several built-in features and best practices to help you optimize your documentation site for search engines like Google, Bing, and DuckDuckGo.

This guide covers the essential strategies and configurations to maximize the SEO potential of your SmartGen Docs project.

1. Configuring Site Metadata

The foundation of good SEO starts with accurate and descriptive metadata in your smartgen.yml configuration file. Search engines use this information to understand the purpose and content of your site.

Essential smartgen.yml Settings

Ensure the following fields are properly configured in your smartgen.yml:

site_name: SmartGen Docs - The Ultimate Static Site Generator
site_url: https://bayeziddev.github.io/smartGenDocs/
site_author: Sayad Md Bayezid Hosan
site_description: Comprehensive documentation, tutorials, and API references for SmartGen Docs. Learn how to build fast, beautiful, and searchable static documentation sites.
  • site_name: This is appended to the title of every page (e.g., "Configuration Guide - SmartGen Docs"). Keep it concise and relevant.
  • site_url: Crucial for SEO. This must be the exact, absolute URL where your site is hosted. It is used to generate canonical links and sitemaps.
  • site_description: A compelling summary of your project. This often appears as the snippet in search engine results pages (SERPs).

2. Page-Level Metadata (Front Matter)

While smartgen.yml sets the global metadata, you can (and should) override these settings on a per-page basis using YAML front matter at the top of your Markdown files.

This allows you to provide highly specific titles and descriptions for individual pages, which significantly improves their ranking for relevant search queries.

Example Front Matter

---
title: Advanced Theming Techniques
description: Learn how to create custom Jinja2 templates and override CSS variables to build a unique theme for your SmartGen Docs site.
keywords: SmartGen Docs theming, custom templates, CSS variables, Jinja2
---

# Advanced Theming Techniques

... content ...
  • title: Overrides the default title generated from the first <h1> heading. Make it descriptive and keyword-rich.
  • description: Overrides the global site_description. Write a unique, compelling summary of the page's content (aim for 150-160 characters).
  • keywords: A comma-separated list of relevant keywords. While less important for Google today, they can still be useful for internal search and other search engines.

3. Canonical URLs

Canonical URLs tell search engines which version of a page is the "master" or preferred version. This prevents duplicate content issues if your site is accessible via multiple URLs (e.g., http://example.com and https://example.com, or with and without a trailing slash).

SmartGen Docs automatically generates canonical links for every page, provided you have correctly set the site_url in your smartgen.yml.

The generated HTML will include a tag like this in the <head>:

<link rel="canonical" href="https://bayeziddev.github.io/smartGenDocs/guides/seo/">

4. Sitemaps

A sitemap is an XML file that lists all the pages on your website, helping search engines discover and index your content more efficiently.

SmartGen Docs automatically generates a sitemap.xml file in the root of your output directory (site/) during the build process.

Submitting Your Sitemap

To ensure search engines find your sitemap, you should submit it to their respective webmaster tools:

  • Google Search Console: Add your property and submit the URL to your sitemap (e.g., https://bayeziddev.github.io/smartGenDocs/sitemap.xml).
  • Bing Webmaster Tools: Similar process to Google.

You can also add a reference to your sitemap in your robots.txt file (if you create one):

Sitemap: https://bayeziddev.github.io/smartGenDocs/sitemap.xml

5. Content Structure and Formatting

How you write and structure your Markdown content directly impacts SEO.

Use Semantic Headings

Use headings (#, ##, ###) logically to structure your content. Search engines use headings to understand the hierarchy and main topics of a page.

  • Only one <h1> per page: This should be the main title of the document. SmartGen Docs themes typically handle this automatically based on your Markdown or front matter.
  • Use <h2> and <h3> for sub-sections: Ensure they flow logically and contain relevant keywords.

When linking to other pages (internal or external), use descriptive anchor text. Avoid generic phrases like "click here" or "read more."

Good:

Learn more about [configuring your site metadata](configuration.md#site-metadata).

Bad:

To learn about configuration, [click here](configuration.md).

Image Alt Text

Always provide descriptive alt text for images. This is crucial for accessibility and helps search engines understand the content of the image.

![SmartGen Docs Architecture Diagram](../assets/architecture-diagram.png)

6. Open Graph and Twitter Cards

To ensure your documentation looks great when shared on social media platforms (like Twitter, LinkedIn, and Facebook), SmartGen Docs themes often support Open Graph and Twitter Card meta tags.

These tags are typically populated automatically using the site_name, site_description, and page-level front matter.

If your chosen theme supports it, you can often specify a default social sharing image in your smartgen.yml:

theme:
  # ... other theme settings ...
  logo: assets/logo.png # Often used as a fallback image

You can also specify a specific image for a page in its front matter:

---
title: Release 2.0 is Here!
image: assets/release-2.0-banner.png
---

7. Performance and Mobile Friendliness

Search engines prioritize fast-loading, mobile-friendly websites.

  • Performance: SmartGen Docs generates static HTML, which is inherently fast. Ensure you optimize your images and avoid loading unnecessary external scripts. Refer to the Performance Guide for more details.
  • Mobile Friendliness: The default themes provided by SmartGen Docs are fully responsive and designed to work well on mobile devices.

By following these guidelines and leveraging the built-in features of SmartGen Docs, you can significantly improve the visibility and reach of your project's documentation.

See Also

Previous Next