# Project configuration

Retype will read the retype.yml file for additional instructions on how to configure and build your project.

The retype.yml file is typically placed in the root of your project, although it can be placed elsewhere. Please ensure the input and output paths are correct if moved to a different location.

The retype.yml file is actually optional (not required), but is recommended as you will almost certainly want to customize some options, so adding a retype.yml is a good first step.

If you run the command retype watch and do not have a retype.yml project configuration file within the root of your project, Retype will auto-generate a simple retype.yml file for your project. You can then edit the file to customize your project.

You can also explicitly have Retype generate a retype.yml file by running the command retype init.

The following sample demonstrates a common set of project configuration options and everything can be customized to your requirements.

Sample retype.yml
input: .
output: .retype
url: # Add your website address here
branding:
  title: Project Name
  label: Docs
links:
  - text: Getting Started
    link: https://retype.com/guides/getting-started/
footer:
  copyright: "© Copyright {{ year }}. All rights reserved."

# branding

Branding configuration for your Retype generated website.

# title

The main text title added to the upper-left corner of the generated website.

The title can be used in conjunction with logo and logoDark. If a title and logo are configured, both will be added to the website. If only a title is configured, only the text title is used. If only a logo and/or logoDark are configured, only the logos are used.

Set the website title
branding:
  title: Example.com

The above title would create the following branding title in the upper-left corner of the generated website.

# label

Optional logo label text. Default is Docs.

Set a custom label
branding:
  label: Docs

The label is rendered as the following label in the upper-left corner of the generated website, to the right of the title or logo.

One of the following:

  1. The path to a logo file relative to the input, or
  2. An inline <svg> logo

Default is null.

Set a custom label
branding:
  logo: static/logo.png

# logoDark

One of the following:

  1. The path to a logo file (dark mode) relative to the input, or
  2. An inline <svg> logo

Default is null.

Set a custom label
branding:
  logo: static/logo.png
  logoDark: static/logo-dark.png

# colors

Custom color configuration.

# label.text

Set a custom label text color. Default is #1f7aff.

branding:
  colors:
    label:
      text: #ffffff

# label.background

Set a custom label background color. Default is #e1edff.

branding:
  colors:
    label:
      background: #ff0000

# cname

By default, if the url is set, Retype will automatically generate a CNAME file. This can be disabled by setting cname: false.

Disable CNAME file generation
cname: false

If you do want a CNAME file generated, but for some reason require a value different than what the url creates, you can explicitly set instruct Retype to generate the CNAME with a different value.

This would be a highly unusual scenario, but Retype does allow you to configure these values separately, just in case you need it. We HIGHLY recommend that you just stick with setting the url.

Custom CNAME file value
cname: docs.example.com

# edit

The edit config allows for enabling and customization of the Edit this page links on content pages.

# repo

The repository URL where the source files for this project are located.

Setting a repo value will enable the Edit this page links on all content pages.

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

You can also configurate the links to point directly to the /edit/ view of the page:

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

# branch

Point to a custom branch within the repo. Default is main.

edit:
  repo: "https://github.com/your-organization/your-repo"
  branch: website

# label

A custom label for the link. Default is "Edit this page".

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

# exclude

Retype can exclude files or folders from being built or copied to the output by configuring an exclude list within your projects retype.yml file.

Exclude patterns are similar to allowable patterns within a .gitignore file. The wildcards ?, *, **, and ! are supported.

The following sample demonstrates how to exclude an entire draft/ folder, any folder that ends with *_temp/, and one specific /src/temp.md file.

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

You could exclude everything in your project with by adding exclude: [ * ].

To explicitly include any files or folders that might have been excluded, please see the include config.


# favicon

A custom path to a .ico or .png file to be used as the favicon. Default is null.

The path is relative to the input.

Favicon is stored in the /static folder
favicon: static/favicon.png

By default, Retype will look for a favicon.ico or favicon.png within the root of the input. The favicon config would typically only be used if you want to store the favicon file in a subfolder of the output root.


# footer

# copyright

Site-wide copyright statement that will be added to the footer of each page. Supports Markdown syntax and {{ year }} variable.

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

# links (footer)

The footer.links have the same configuration options as links.

footer:
  links:
    - text: License
      link: license.md

# include

Retype can explicitly include files or folders that might have been excluded by default or excluded within the exclude config.

Include patterns are similar to allowable patterns within a .gitignore file. The wildcards ?, *, **, and ! are supported.

The following sample demonstrates how to include all .py files and the entire contents of any www folder within the project.

Include patterns
include:
  - *.py
  - **/www/**

You could explicitly include everything in your project with include: [ * ], BUT be careful as all files within your input will be publicly availble once your website is published. We would not recommend doing this, but it's your call. 😨

Retype treats all .md and .yml files as parsable content files that will be converted into .html files and are not copied over to the output. All other included file types would be copied straight across to the output unchanged and become static files that can be linked to.

By default, if Retype discovers any of the following file types, they will be automatically included and copied over to the output unchanged. If you require any other file types, they would need to be explicitly added to the include config.

Included file types:

  • *.gif
  • *.heif
  • *.jpeg
  • *.jpg
  • *.png
  • *.svg
  • *.webp
  • *.ai
  • *.bmp
  • *.eps
  • *.pdf
  • *.tiff
  • *.txt

By default, if Retype discovers any of the following folders anywhere within the project, the folder and its entire contents will be copied over to the output unchanged. If you require any other folders, please add to the include config.

Included folders:

  • **/static/**
  • **/public/**
  • **/assets/**
  • **/resources/**

If you would rather not include certain folders, files, or file types, please add the pattern to the exclude config.


# input

Custom path to the input directory. Default is ..

The path is relative to the retype.yml location.

Change input location to /src folder
input: ./src

# integrations

More integrations will be added over time. Do you have an integration suggestion? let us know.

# googleAnalytics

Add Google Analytics to your website.

Google Analytics ID value.

integrations:
  googleAnalytics:
    id: UA-12345678-1

# links

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

The following sample demonstrates a basic links scenario which would add one link to the top bar of all pages.

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

# text

The link text label.

links:
  - text: Demos
    link: https://demo.example.com/

# link

The URL to use for the link. The link can be a .md file name, or to any internal path, or to any external URL.

If a .md file set, such as sample.md, Retype will automatically resolve the path and in the generated website, the sample.md value will be replaced with the path to the actual generated HTML file.

links:
  - text: About us
    link: /about/

# icon

An icon to use with the link. Default is null.

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

Options include using an Octicon name, Emoji shortcode, <svg> element, or a path to an image file.

Octicon
icon: rocket
Emoji shortcode
icon: :rocket:
SVG element
icon: <svg>...</svg>
Path
icon: ../static/rocket.png

# iconAlign

The position for the icon relative to the link text. Either left or right. Default is left.

links:
  - text: Demos
    link: https://demo.example.com/
    icon: link-external
    iconAlign: right

# target

Sets the target attribute of the hyperlink and specifies which window or tab to open the link into.

links:
  - text: Demos
    link: https://demo.example.com/
    target: blank

If no target is configured, the link will open in the current tab.

The target can be set to any value, although blank is common and will open the link in a new tab. Retype will automatically transform the value blank into _blank which is the actual value required by the browser to indicate that a hyperlink should be opened in a new tab.

There are several other values that may be prefixed with an _ character, including self, parent, and top. The following table demonstrates some common scenarios and naming convention used by Retype to normalize the target values.

Config target value Runtime target value
blank _blank
parent _parent
top _top
self _self
news1 news1
nEWs2 news2
recent NEWS recent-news

# meta

Project wide meta tag configuration options.

# title

Common site-wide suffix appended to the html <title> element of all pages. Default is null.

Append this string to all page meta tag titles
meta:
  title: " | Example.com - Widgets for the internet"

If we had an About us page, the final <title> with the title value above would be:

<title>About us | Example.com - Widgets for the internet</title>

# output

Custom path to the output directory. Default is .retype.

The path is relative to the retype.yml location.

Change output location to /docs folder
output: ./docs

# search

Customization of the website search component.

# minChars

Min number of characters required in a search query. Default is 3.

search:
  minChars: 3

# maxResults

Max number of search results to render. Default is 20.

search:
  maxResults: 20

# placeholder

Placeholder text rendered on the search component. Default is "Search".

search:
  placeholder: Search

# hotkeys

Keyboard key to set the cursor focus into the search field. Default is ["/"].

search:
  hotkeys:
    - "/"

# noResultsFoundMsg

Message rendered when no results were found. Default is "Sorry, no results found.".

search:
  noResultsFoundMsg: Sorry, no results found.

# server

Custom configuration for the built in Retype development web server.

# host

Serve the website from this host location. Default is localhost.

server:
  host: 127.0.0.1

By default, the Retype development web server will serve from http://localhost:5000, although the port could be dynamically assigned if port 5000 is already in use.

A custom port value can also be assigned.

server:
  host: 127.0.0.1:5005

A custom --host value can also be passed as an argument to the retype watch and retype run commands. If included, the --host value will override the host set within your retype.yml project configuration file.

retype watch --host 127.0.0.1              # serve from a custom host
retype watch --host 127.0.0.1 --port 5005  # serve from a custom host and port

# port

A custom port for the internal Retype development web server to use when hosting locally. Default is 5000.

server:
  port: 5005

If the default port is already being used by another service, Retype will auto-increment the port number until it finds an open port to host from.

If a custom port is explicitly configured in the retype.yml and if that port is already being used by another service, Retype will write a message to the console and exit. In that scenario, because the port was explicitly configured, Retype will not attempt to auto-increment.

A custom --port value can also be passed as an argument to the retype watch and retype run commands. If included, the --port value will override the port set within your retype.yml project configuration file.

retype watch --port 5005  # serve from a custom port

# watch

Custom configuration for the retype watch command.

During retype watch, the mode configuration instructs the web server on where to host files from.

If memory, the entire website is built and then stored in memory during development with no files being written to disk.

If disk, the entire website is built and written to disk, then the web server will host those files from their disk location.

Default is memory.

Mode Description
memory No output files are written to a disk. Retype serves a website from the in-memory storage.
disk Output files are written to the output directory, and updated with each incremental build accordingly.
server:
  watch:
    mode: disk

The command retype build will always build and write all files to disk. The memory configuration is not an option with retype build. The Retype GitHub Action uses retype build. The command retype watch is only to be used during local development.


# snippets

The snippets configuration allows for the project with custom configuration of code block formatting, including the project wide enabling of line numbering.

# lineNumbers

A list of code block reference language strings to enable line numbering on. Default is null.

Enable line numbering for js and json code blocks site wide
snippets:
  lineNumbers:
    - js
    - json

Configuring the "*" wildcard will enable line numbering for all code block types, including code blocks with no explicit reference language.

Enable line numbering for all code blocks site wide
snippets:
  lineNumbers:
    - *

Enabling line numbering site wide on code blocks with no explicit reference language is configured with the none "none" specifier.

Enable line numbering for all unspecified code blocks site wide
snippets:
  lineNumbers:
    - none

# url

The base URL of your website.

url: example.com

The url can also be a sub-domain.

url: docs.example.com

If you deploy your Retype generated website into the subfolder of another website, add the subfolder in the url. For example, if the website will be available at https://example.com/docs, add that docs folder name to the url.

url: example.com/docs

If no protocol is supplied, such as https or http, Retype will assume https. A protocol can be explicitly defined by passing in the url.

url: http://example.com/docs/

Another common scenario for setting a url is when using GitHub Pages without a custom CNAME.

For instance, if your GitHub organization was CompanyX and your repo was named docs, the URL to your GitHub Pages hosted website would be https://companyx.github.io/docs/.

Retype needs to know where your website will be hosted, so the url configuration for the above scenario would be:

url: companyx.github.io/docs

# Additional options

Option Type Default value Description
api object API reference doc generation
api.input string Path to a project file or a project directory
api.output string ./api Custom path to the API output directory. Relative to output