Skip to content

hugo

Class HugoPage

@dataclasses.dataclass
class HugoPage(GenericPage["HugoPage"])

[view_source]

A subclass of {@link pydoc:pydoc_markdown.util.pages.Page} which adds Hugo-specific overrides.

Options

preamble

The Hugo preamble of the page. This is merged with the HugoRenderer.default_preamble.

directory

Override the directory that this page is rendered into (relative to the content directory). Defaults to null.

Class HugoConfig

@dataclasses.dataclass
class HugoConfig()

[view_source]

Represents the Hugo configuration file that is rendered into the build directory.

Options

title

Title of the site. This is a mandatory field.

theme

The theme of the site. This is a mandatory field. It must be a string, a HugoThemePath or a HugoThemeGitUrl object. Examples:

theme: antarctica
theme: {clone_url: "https://github.com/alex-shpak/hugo-book.git"}
theme: docs/hugo-theme/

baseURL

Base URL.

serverURL

Server URL. Default: 127.0.0.1 aka localhost

serverPort

Server Port. Default: 1313

languageCode

Language code. Default: en-us

Class HugoRenderer

@dataclasses.dataclass
class HugoRenderer(Renderer, Server, Builder)

[view_source]

A renderer that produces Markdown files compatible with Hugo. The --bootstrap hugo option can be used to create a Pydoc-Markdown configuration file with the Hugo template.

  • Adds a YAML preamble to every generated Markdown file.
  • Produces files in a layout suitable for Hugo (e.g. _index.md files).
  • Produces a config.yaml if config is not set to null.
  • Can be used with the Pydoc-Markdown --server option to live-preview the generated docs.
  • Downloads a suitable Hugo binary from Github if Hugo is not already installed (see get_hugo).

Example configuration:

renderer:
  type: hugo
  config:
    title: My Project
    theme: {clone_url: "https://github.com/alex-shpak/hugo-book.git"}
  # The "book" theme only renders pages in "content/docs" into the nav.
  content_directory: content/docs
  default_preamble: {menu: main}
  pages:
    - title: Home
      name: index
      source: README.md
    - title: API Documentation
      contents:
        - '*'

Options

build_directory

The directory where all generated files are placed. Default: build/docs

content_directory

The directory inside the build directory where the generated pages are written to. Default: content

clean_render

Clean up files that were previously generated by the renderer before the next render pass. Defaults to True.

pages

The pages to render.

default_preamble

The default Hugo preamble that is applied to every page. Example:

default_preamble:
  menu: main

markdown

The MarkdownRenderer configuration.

config

The contents of the Hugo config.toml file as YAML. This can be set to null in order to not produce the config.toml file in the build_directory. Must be deserializable into a HugoConfig.

get_hugo

Options for when the Hugo binary is not present and should be downloaded automatically. Example:

get_hugo:
  enabled: true
  version: '0.71'
  extended: true

install_hugo

def install_hugo(to: str,
                 version: str | None = None,
                 extended: bool = True) -> None

[view_source]

Downloads the latest release of Hugo from Github

and places it at the path specified by to. This will install the extended version if it is available and extended is set to True.

Arguments:

  • to: The file to write the Hugo binary to.
  • version: The Hugo version to get. If not specified, the latest release will be used.
  • extended: Whether to download the "Hugo extended" version. Defaults to True.

get_github_releases

def get_github_releases(repo: str) -> t.Generator[dict, None, None]

[view_source]

Returns an iterator for all releases of a Github repository.

def parse_links_header(link_header: str) -> t.Dict[str, str]

[view_source]

Parses the Link HTTP header and returns a map of the links. Logic from PageLinks.java.