Skip to main content

Sitemap generator for Sphinx

Project description

A Sphinx extension to generate multiversion and multilanguage sitemaps.org compliant sitemaps for the HTML version of your Sphinx documentation.

Build Status PyPI version Downloads License: MIT

Installing

Directly install via pip by using:

pip install sphinx-sitemap

Add sphinx_sitemap to the extensions array in your Sphinx conf.py. For example:

extensions = ['sphinx_sitemap']

Base Configuration

Set the value of html_baseurl in your Sphinx conf.py to the current base URL of your documentation. For example:

html_baseurl = 'https://my-site.com/docs/'

After the HTML build is done, sphinx-sitemap will output the location of the sitemap:

sitemap.xml was generated for URL https://my-site.com/docs/ in /path/to/_build/sitemap.xml

Tip: Make sure to confirm the accuracy of the sitemap after installs and upgrades.

Changing the Filename

Set sitemap_filename in conf.py to the desired filename, for example:

sitemap_filename = "sitemap.xml"

Versioning Configuration

For multiversion sitemaps, you have to generate a sitemap per version and then manually add their locations to a sitemapindex file.

The extension will look at the version config value for the current version being built, so make sure that is set.

Note: When using multiple versions, it is best practice to set the canonical URL in the theme layout of all versions to the latest version of that page:

<link rel="canonical" href="https://my-site.com/docs/latest/index.html"/>

Multilingual Configuration

For multilingual sitemaps, you have to generate a sitemap per language/locale and then manually add their locations to a sitemapindex file.

Primary language is language config value. Alternative languages are either manually set by sitemap_locales option or auto-detected by the extension from the locale_dirs config value, so make sure one of those is set.

sitemap_locales configuration is handy you want to list in the sitemap only some locales. For instance, if a third-party extension adds locale_dirs to Sphinx for the languages which you don’t support in your docs, or if you want to wait for locales to reach a certain translated percentage before making them public. For example, if primary language is en, and you have es and fr translations, the sitemap look like this:

<?xml version="1.0" encoding="utf-8"?>
  <urlset xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
    <url>
      <loc>https://my-site.com/docs/en/index.html</loc>
      <xhtml:link href="https://my-site.com/docs/es/index.html" hreflang="es" rel="alternate"/>
      <xhtml:link href="https://my-site.com/docs/fr/index.html" hreflang="fr" rel="alternate"/>
      <xhtml:link href="https://my-site.com/docs/en/index.html" hreflang="en" rel="alternate"/>
    </url>
    <url>
        <loc>https://my-site.com/docs/en/about.html</loc>
        <xhtml:link href="https://my-site.com/docs/es/about.html" hreflang="es" rel="alternate"/>
        <xhtml:link href="https://my-site.com/docs/fr/about.html" hreflang="fr" rel="alternate"/>
        <xhtml:link href="https://my-site.com/docs/en/about.html" hreflang="en" rel="alternate"/>
    </url>
  </urlset>

If you limit the sitemap locales:

sitemap_locales = ['en', 'es']

The end result is something like the following for each language/version build:

<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://my-site.com/docs/en/index.html</loc>
    <xhtml:link href="https://my-site.com/docs/es/index.html" hreflang="es" rel="alternate"/>
  </url>
  <url>
    <loc>https://my-site.com/docs/en/about.html</loc>
    <xhtml:link href="https://my-site.com/docs/es/about.html" hreflang="es" rel="alternate"/>
  </url>
</urlset>

If you set the special value of [None]:

sitemap_locales = [None]

only primary language is generated:

<?xml version="1.0" encoding="utf-8"?>
<urlset xmlns:xhtml="http://www.w3.org/1999/xhtml" xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://my-site.com/docs/en/index.html</loc>
  </url>
  <url>
    <loc>https://my-site.com/docs/en/about.html</loc>
  </url>
</urlset>

Customizing the URL Scheme

If you have both language and version set, the default URL format is {version}{lang}{link}. To change the default behavior, set the value of sitemap_url_scheme in conf.py to the desired format. For example:

sitemap_url_scheme = "{lang}{version}subdir/{link}"

Note: The extension is currently opinionated, in that it automatically appends trailing slashes to both the language and version values. You can also omit values from the scheme for desired behavior.

Getting the Most out of the Sitemap

  1. Add a robots.txt file in the source directory which contains a link to the sitemap or sitemapindex. For example:

    User-agent: *
    
    Sitemap: https://my-site.com/docs/sitemap.xml

    Then, add robots.txt to the html_extra_path config value:

    html_extra_path = ['robots.txt']
  2. Submit the sitemap or sitemapindex to the appropriate search engine tools.

See Who Is Using It

You can use GitHub search or libraries.io to see who is using sphinx-sitemap.

Contributing

Pull Requests welcome! See CONTRIBUTING for instructions on how best to contribute.

License

sphinx-sitemap is made available under a MIT license; see LICENSE for details.

Originally based on the sitemap generator in the guzzle_sphinx_theme project, also licensed under the MIT license.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-sitemap-2.2.0.tar.gz (6.1 kB view details)

Uploaded Source

File details

Details for the file sphinx-sitemap-2.2.0.tar.gz.

File metadata

  • Download URL: sphinx-sitemap-2.2.0.tar.gz
  • Upload date:
  • Size: 6.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.15.0 pkginfo/1.5.0.1 requests/2.24.0 setuptools/20.7.0 requests-toolbelt/0.8.0 tqdm/4.40.2 CPython/3.5.2

File hashes

Hashes for sphinx-sitemap-2.2.0.tar.gz
Algorithm Hash digest
SHA256 65adda39233cb17c0da10ba1cebaa2df73e271cdb6f8efd5cec8eef3b3cf7737
MD5 8e16372c11277be90f7dd118847439e7
BLAKE2b-256 94d4408579f209dfc6c95e0b31e72e67cc94de78dfb8936b1009f68b4d56d7f5

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page