# Project configuration

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

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

After making a change to the retype.json, if you are running retype watch, Retype will automatically rebuild the project for you and your web browser will refresh with the changes.

If you started the local web server using retype run, you'll need to call retype build to regenerate a sparkly fresh new build of the project, then manually refresh your web browser to see update.

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

Running the command retype init will create a default retype.json file. The following sample demonstrates a common set of configuration options and everything can be customized to your requirements.

Sample retype.json
{
  "input": ".",
  "output": ".retype",

  "branding": {
    "title": "Project Name",
    "label": "Docs"
  },

  "links": [
    {
      "text": "Getting Started",
      "link": "https://retype.com/getting-started/"
    }
  ],

  "footer": {
    "copyright": "© Copyright {{ year }}. All rights reserved."
  }
}

# base

Base subfolder path appended to all URL's. Default is null or empty string.

If you deploy the build website to a subfolder of another website, use the base to ensure the URL's correclty resolve.

For instance, let's say your main site is https://example.com and will remain unchanged. If you would like to deploy the Retype built website into a /docs subfolder, with the final URL of https://example.com/docs, then setting "base": "docs" would be required.

Sample: Change output location to /docs folder
{
  "base": "docs"
}

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

For instance, if your GitHub organization was CompanyX and your repo was named my-repo, the URL to your GitHub Pages hosted website would be:

https://companyx.github.io/my-repo/

The Retype generated wesite would require "base": "my-repo" to be set within your projects retype.json file in order to properly resolve the URL paths during build.

The retype.json file for that scenario would be...

retype.json
{
  "base": "my-repo"
}

...and the GitHub Pages configuration within your repo Settings would be:


# branding

Branding configuration for your Retype generated website.

# title

Logo Title. Displayed when logo and logoDark are not configured. Default is Project Name.

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": "v2.2"
  }
}

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

If specified, a CNAME file with the corresponding value will be created and added to the root of the output. Default is null.

Sample: Host docs.example.com website using GitHub pages
{
  "cname": "docs.example.com"
}

# edit

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

Check out the bottom of this page for a working sample of Edit this page.

# 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"
  }
}

# branch

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

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

# base

A base folder within from the root of the project where the source content files are located. By default, the root of the repo is assumed.

The following sample demonstrates a scenario where the content files are located within the /docs sub-folder of the repo.

{
  "edit": {
    "repo": "https://github.com/your-organization/your-repo",
    "base": "docs"
  }
}

# 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.json 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": [ "*" ].

By default, any file or folder name prefixed with a . or a _ will be excluded.

As well, any node_modules folder will be excluded.

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.come/) All rights reserved.",
  }
}

# links (footer)

Same configuration options as page level 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
  • *.zip

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.json 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.

{
  "plugins": {
    "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 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 internal or external.

{
  "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"
    }
  ]
}

# meta

Meta tag configuration.

# 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.json location.

Sample: Change output location to /docs folder
{
  "output": "./docs"
}

# port

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

{
  "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.json, 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.


# search

Customization of the website search component.

# minChars

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

{
  "search": {
    "minChars": 3
  }
}

# maxResults

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

{
  "search": {
    "maxResults": 20
  }
}

# placeholder

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

{
  "search": {
    "placeholder": "Search"
  }
}

# hotkeys

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

{
  "search": {
    "hotkeys": ["/"]
  }
}

# noResultsFoundMsg

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

{
  "search": {
    "noResultsFoundMsg": "Sorry, no results found."
  }
}

# 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 llist 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" ]
  }
}

# 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