Project configuration

Retype reads the retype.yml file for instructions on how to configure and build your project. The file is typically placed in the root of your project.

When running retype start, any changes to retype.yml are automatically detected and the website is regenerated in the browser. If you started the server with retype serve, you need to run retype build manually and refresh the browser.

The retype.yml file is optional but recommended. If you run retype start without one, Retype will auto-generate a basic retype.yml you can then customize. You can also run retype init to generate it explicitly.

Sample retype.yml

retype.yml

input: .
output: .retype

url: docs.example.com

start:
  pro: true  # Try Retype Pro features locally

branding:
  title: Project Name
  label: Docs

links:
  - text: Getting Started
    link: https://retype.com/guides/getting-started/

footer:
  copyright: "&copy; Copyright {{ year }}. All rights reserved."

input

string

default:"."

Custom path to the input directory. The path is relative to the retype.yml location.

input: ./src

output

string

default:".retype"

Custom path to the output directory. The path is relative to the retype.yml location.

output: ./docs

The output directory is only used by retype build. When using retype start, files are stored in memory and not written to disk.

url

string

The base URL of your website. Retype uses this to construct absolute links and generate a CNAME file.

url: docs.example.com

Subdomains, paths, and explicit protocols are all supported:

url: example.com/docs
url: http://example.com/docs/
url: companyx.github.io/docs  # GitHub Pages without custom CNAME

If no protocol is supplied, Retype assumes https.

branding

Branding configuration for your Retype generated website.

branding.title

string

The main text title shown in the upper-left corner of the generated website. Can be used alongside logo and logoDark.

branding:
  title: Example.com

branding.label

string

default:"Docs"

Optional logo label text rendered to the right of the title or logo in the upper-left corner.

branding:
  label: Docs

branding.logo

string

Path to a logo image file relative to input, or an inline <svg> string. Default is null.

branding:
  logo: static/logo.png

branding.logoDark

string

Path to a dark mode logo image relative to input, or an inline <svg> string. Default is null.

branding:
  logo: static/logo.png
  logoDark: static/logo-dark.png

branding.logoWidth

number

Custom width (in pixels) for the branding logo. If not set, Retype auto-detects the intrinsic width.

branding:
  logo: ./logo.svg
  logoWidth: 150

branding.logoHeight

number

Custom height (in pixels) for the branding logo. If not set, Retype auto-detects the intrinsic height.

branding:
  logo: ./logo.svg
  logoHeight: 31

branding.logoAlign

string

default:"left"

Logo alignment relative to the title. Accepted values: left, right.

branding:
  logo: static/logo.png
  logoAlign: right

branding.baseColor

string

default:"#5495f1"

Retype Pro only. Sets the main brand color as a shorthand for theme.base.base-color.

branding:
  baseColor: "#8839ef"

branding.colors.label

object

Override text and background colors for the branding label badge.

Option	Type	Description
`text`	`string`	Label text color
`background`	`string`	Label background color

branding:
  colors:
    label:
      text: "#ffffff"
      background: "#ff0000"

links

Custom links added to the top-bar navigation of all pages.

links:
  - text: Getting Started
    link: https://retype.com/getting_started/

links[].text

string

The link text label.

links[].link

string

The URL for the link. Accepts a .md filename, internal path, or external URL.

links[].icon

string

An icon for the link. Accepts an Octicon name, emoji shortcode, <svg> element, or path to an image file.

links:
  - text: Issues
    link: https://github.com/retypeapp/retype/issues/
    icon: bug

links[].iconAlign

string

default:"left"

Position of the icon relative to the link text. Accepted values: left, right.

links[].target

string

Sets the target attribute of the hyperlink. Use blank to open in a new tab (Retype automatically transforms blank → _blank).

links[].title

string

Sets the title attribute on the hyperlink, shown as a browser tooltip on hover.

links[].items

list

Nested menu items that render the parent link as a dropdown in the header navigation. Dropdown menus are supported one level deep. Each nested item supports the same properties as top-level links.

links:
  - text: Guides
    items:
      - text: Installation
        link: /guides/installation.md
        icon: download
      - text: Configuration
        link: /configuration/project.md

footer.copyright

string

Site-wide copyright statement added to the footer of every page. Supports Markdown and the {{ year }} template variable.

footer:
  copyright: "© Copyright {{ year }}. [Example, Inc.](https://example.com/) All rights reserved."

footer.links

object

Footer links use the same configuration options as top-level links.

footer:
  links:
    - text: License
      link: license.md
    - text: Support
      link: https://github.com/retypeapp/retype/discussions/

edit

Enables and customizes Edit this page links on content pages.

edit.repo

string

The repository URL where source files are hosted. Setting this value enables Edit this page links.

edit:
  repo: "https://github.com/<your-organization>/<your-repo>/"

To link directly to the edit view:

edit:
  repo: "https://github.com/<your-organization>/<your-repo>/edit/"

edit.base

string

Optional base path to a subdirectory within the repository where the .md source files are stored.

edit:
  repo: "https://github.com/your-org/your-repo"
  base: /src/docs

edit.branch

string

default:"main"

The branch to point to within the repo.

edit:
  repo: "https://github.com/your-org/your-repo"
  branch: master

edit.label

string

default:"Edit this page"

Custom label text for the edit link.

edit:
  repo: "https://github.com/your-org/your-repo"
  label: Edit on GitHub

nav

Navigation configuration for the left sidebar.

nav.mode

string

default:"default"

Retype Pro only. Controls how the sidebar navigation is structured.

Option	Description
`default`	Expandable/collapsible tree structure
`stack`	Top-level folders are always expanded, creating a stacked layout

nav:
  mode: stack

nav.icons.mode

string

default:"all"

Retype Pro only. Controls how icons are displayed in the left sidebar.

Mode	Description
`all`	Show icons for all navigation items
`folders`	Show icons only for folder items
`pages`	Show icons only for page items
`top`	Show icons only for top-level items
`none`	Hide all navigation icons

nav:
  icons:
    mode: none

Value	Description
`2`	H2 headings only
`2-3`	H2 to H3 (default)
`1-4`	H1 to H4
`2,4`	H2 and H4 only

search

Customization options for the website search component.

search.mode

string

default:"full"

The search index creation mode.

Mode	Description
`full`	Full-text index of all headings and content
`partial`	All headings plus first paragraph under each heading
`basic`	All headings plus only the first paragraph per page

search:
  mode: partial

If search feels slow on a large project, try partial or basic mode.

search.hotkeys

list

default:"k"

Keyboard key(s) to focus the search field.

search:
  hotkeys:
    - "/"

search.maxResults

number

default:"20"

Maximum number of search results to display.

search.minChars

number

default:"2"

Minimum number of characters required before a search query is run.

search.placeholder

string

default:"Search"

Placeholder text displayed in the search input.

search.noResultsFoundMsg

string

default:"Sorry, no results found."

Message shown when no results are returned.

search.excludeCode

boolean

default:"false"

Exclude code blocks from the search index.

search:
  excludeCode: true

search.exclude

list

Retype Pro only. Exclude pages or folders from the search index while still generating them in the website. Uses the same wildcard patterns as exclude.

search:
  exclude:
    - /blog
    - /draft

search.preload

boolean

default:"false"

Preload the search index on page load. Useful when combined with generator.directoryIndex.append: true for offline filesystem browsing.

theme

Retype Pro only. Customize your site’s visual appearance by overriding CSS design variables. See the full theme variables reference for all available variables.

theme.base

object

Light mode theme variables. All theme variables can be customized here.

theme:
  base:
    base-color: "#8839ef"
    base-bg: "#eff1f5"
    primary: "#1e66f5"
    success: "#40a02b"
    danger: "#d20f39"
    warning: "#df8e1d"

theme.dark

object

Dark mode theme variables. These override theme.base variables when dark mode is active.

theme:
  dark:
    base-color: "#ca9ee6"
    base-bg: "#303446"

integrations

Google Analytics

integrations.googleAnalytics.id

string

Google Analytics measurement ID.

integrations:
  googleAnalytics:
    id: A-BCDEFGHIJ1

Google Tag Manager

integrations.googleTagManager.id

string

Google Tag Manager container ID.

integrations:
  googleTagManager:
    id: GTM-XXXXXXX

Plausible Analytics

integrations.plausible.domain

string

The domain registered in your Plausible account. Multiple domains can be separated by commas.

integrations:
  plausible:
    domain: example.com

integrations.plausible.host

string

Custom Plausible host for self-hosted deployments.

integrations:
  plausible:
    host: plausible.example.com

include and exclude

exclude

list

Exclude files or folders from the build output. Uses .gitignore-style patterns with support for ?, *, **, and !.

exclude:
  - "draft/"
  - "*_temp/"
  - "/src/temp.md"

Files and folders prefixed with . or _, and any node_modules folder, are excluded by default.

include

list

Explicitly include files or folders that would otherwise be excluded. Retype automatically includes common image formats, PDFs, ZIPs, and the static/, public/, assets/, and resources/ folders.

include:
  - "*.py"
  - "demo*.js"
  - "**/www/**"

favicon

string

Path to a custom .ico or .png favicon, relative to input. By default, Retype looks for favicon.ico or favicon.png in the root of input.

favicon: static/favicon.png

locale

string

default:"en"

The primary language for the generated website. Retype supports 24 languages. Provide an ISO language code.

locale: fr

Supported codes include: ar, da, de, el, en, es, fi, fr, he, hi, hu, hy, it, ja, ko, nb, nl, pt, pt-PT, ro, ru, sv, tr, zh, and more.

locale.dateFormat

string

Configure how dates are rendered across the site, including blog dates and the Last Updated component.

locale:
  dateFormat: MM-dd-yyyy

Supported specifiers: yyyy, yy, MMMM, MMM, MM, M, dddd, ddd, dd, d.

scheme

Retype Pro only. Control the default color mode for the website.

scheme.mode

string

default:"system"

Sets the default color scheme.

Mode	Description
`system`	Follow the visitor’s system preference (default)
`dark`	Always render in dark mode
`light`	Always render in light mode

scheme:
  mode: dark

If a visitor manually selects a color mode using the toggle, their choice overrides this setting.

serve

Configuration for the built-in Retype development web server.

serve.host

string

default:"localhost"

Host address for the local development server. A custom port can be appended with a colon.

serve:
  host: 127.0.0.1
  # or with a port:
  # host: 127.0.0.1:5005

serve.port

number

default:"5001"

Port for the local development server. If the port is in use, Retype auto-increments unless a value is explicitly set.

serve:
  port: 5005

start

Options that apply during the retype start command.

start.open

boolean

default:"true"

Set to false to prevent Retype from opening a browser window when retype start is run.

start:
  open: false

start.pro

boolean

default:"false"

Enable Pro mode locally to trial Retype Pro features without a license key.

start:
  pro: true

start.debounce

number

default:"100"

Delay in milliseconds before retype start reacts to file changes.

backlinks

Retype Pro only. Controls the automatic display of inbound links (“See also”) at the bottom of pages.

backlinks.enabled

boolean

default:"true"

Enable or disable backlinks for the entire project.

backlinks:
  enabled: false

backlinks.title

string

default:"See also"

Heading text displayed above the backlinks section.

backlinks:
  title: "Referenced by"

backlinks.maxResults

number

default:"12"

Maximum number of backlinks to display per page.

backlinks.exclude

list

Exclude pages or folders from appearing as backlinks. Supports the same wildcard patterns as exclude.

backlinks:
  exclude:
    - /blog

backlinks.include

list

Explicitly include pages or folders as backlink sources, overriding backlinks.exclude.

backlinks:
  exclude:
    - "*"
  include:
    - /guides

Retype Pro only. Hierarchical breadcrumb navigation.

Enable or disable breadcrumb navigation project-wide.

breadcrumb:
  enabled: false

Customize or remove the first (home) node of the breadcrumb. Set to false to remove it entirely, or provide a label string or icon shortcode.

breadcrumb:
  home: ":icon-home:"  # use an icon

Customize the separator between breadcrumb nodes.

breadcrumb:
  separator: "|"

blog

Configuration for blog summary pages and pagination.

blog.base

string

default:"blog"

URL base path for the blog summary pages.

blog:
  base: news  # pages served at /news/ instead of /blog/

blog.layout

string

default:"blog"

Default layout for all blog posts.

blog.pageSize

number

default:"10"

Number of blog posts per paginated summary page.

blog.maxResults

number

Maximum total blog posts included across all summary pages. Default is unlimited.

blog.title

string

Custom heading title for the blog summary page.

generator

generator.recase

string

default:"all"

Controls how output file and folder names are cased.

Option	Description
`all`	Convert all names to lowercase (default)
`none`	Preserve original casing

generator:
  recase: none

generator.paths

string

default:"relative"

URL kind preference for resolved links: relative, root, or source.

generator.trailingSlash

boolean

default:"true"

Set to false to remove trailing slashes from generated links.

generator.directoryIndex.name

string

default:"index.html"

The default HTML document filename generated by Retype.

generator.directoryIndex.append

boolean

default:"false"

Append the default document filename to resolved URLs (e.g., /guides/index.html instead of /guides/). Useful for offline filesystem browsing.

cache

cache.strategy

string

default:"query"

Cache-busting strategy for JS and CSS assets.

Strategy	Example URL
`none`	`/resources/js/retype.js`
`path`	`/resources/js/retype.v1.10.js`
`query`	`/resources/js/retype.js?v=1.10`

cache:
  strategy: query

cache.token

string

Optional custom cache-busting token. If not set, Retype uses {version}.{milliseconds since 2000-01-01}.

data

object

Custom key-value data available as template variables on all pages.

data:
  productName: Company X
  productVersion: v5.1

Use {{ productName }} in any page to render the value. Nested objects and arrays are supported, and accessible via dot notation.

markdown

markdown.lineBreaks

string

default:"soft"

Controls how single line breaks are handled. soft follows the CommonMark spec; hard emits a <br /> for every line break.

markdown:
  lineBreaks: hard

snippets

snippets.lineNumbers

list

Enable line numbering on code blocks project-wide by listing language identifiers. Use "*" for all languages.

snippets:
  lineNumbers:
    - js
    - json

outbound

Retype Pro only. Customize the behavior of outbound (external) links.

outbound.enabled

boolean

default:"true"

Enable or disable outbound link decoration (external icon + new tab).

outbound.icon

string

default:"link-external"

Icon used for outbound links. Set to "" to disable the icon without disabling the feature.

outbound.target

string

default:"blank"

target attribute for outbound links.

outbound.exclude

list

Domains or URL patterns to exclude from outbound link treatment.

outbound:
  exclude:
    - example.com

cname

boolean | string

By default, Retype auto-generates a CNAME file when url is set. Set to false to disable this behavior.

cname: false

In most cases you should set url and let Retype handle the CNAME file automatically.

showSidebarFilter

boolean

default:"true"

Controls visibility of the filter component above the left sidebar navigation tree.

showSidebarFilter: false

lastUpdated

Controls automatic last-updated footer metadata derived from Git commit history.

lastUpdated.date.enabled

boolean

default:"true"

Enable or disable the auto-generated last updated date in page footers.

lastUpdated.date.source

string

default:"committer"

Git timestamp to use: author or committer.

lastUpdated.by.enabled

boolean

default:"false"

Enable display of who last updated the page.

lastUpdated.by.source

string

default:"committer"

Git identity to use for the by value: author or committer.

In GitHub Actions, add fetch-depth: 0 to your actions/checkout step to ensure full Git history is available for lastUpdated generation.

hub

Retype Pro only. A shortcut link shown to the left of the project logo, useful for linking from a docs subdomain back to the main site.

hub.link

string

URL for the hub link. Setting a value enables the hub.

hub:
  link: https://example.com/

hub.alt

string

Tooltip text for the hub link.

hub.target

string

target attribute for the hub link. Use blank to open in a new tab.

templating

templating.enabled

boolean

default:"true"

Enable or disable the Retype content templating engine project-wide.

templating.liquid

boolean

default:"false"

Enable Liquid {% ... %} syntax. Note: incompatible with GitBook-style component syntax.

templating.loopLimit

number

default:"1000"

Maximum loop iterations allowed in templates. Set to 0 to disable the limit (not recommended).

templating.namespace

string

Optional namespace prefix for template variables. When set, variables are accessed as {{ namespace.project.branding.title }}.

poweredByRetype

boolean

Retype Pro only. Set to false to remove the “Powered by Retype” branding from the footer.

poweredByRetype: false

​Sample retype.yml

​input

​output

​url

​branding

​links

​footer

​meta

​edit

​nav

​toc

​search

​theme

​integrations

​Google Analytics

​Google Tag Manager

​Plausible Analytics

​include and exclude

​favicon

​locale

​scheme

​serve

​start

​backlinks

​breadcrumb

​blog

​generator

​cache

​data

​markdown

​snippets

​outbound

​cname

​showSidebarFilter

​lastUpdated

​hub

​templating

​poweredByRetype

Sample retype.yml

input

output

url

branding

links

footer

meta

edit

nav

toc

search

theme

integrations

Google Analytics

Google Tag Manager

Plausible Analytics

include and exclude

favicon

locale

scheme

serve

start

backlinks

breadcrumb

blog

generator

cache

data

markdown

snippets

outbound

cname

showSidebarFilter

lastUpdated

hub

templating

poweredByRetype