label

order

icon

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.

{
  "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 : string

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.

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

{
  "base": "my-repo"
}

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

branding

Branding configuration for your Retype generated website.

title

=== title : string

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.

{
  "branding": {
    "title": "Example.com"
  }
}

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

label

=== label : string

Optional logo label text. Default is Docs.

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

logo

=== logo : string

One of the following:

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

Default is null.

{
  "branding": {
    "logo": "static/logo.png"
  }
}

===

logoDark

=== logoDark : string

One of the following:

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

Default is null.

{
  "branding": {
    "logo": "static/logo.png",
    "logoDark": "static/logo-dark.png"
  }
}

===

colors

Custom color configuration.

label.text

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

{
  "branding": {
    "colors": {
      "label": {
        "text": "#ffffff"
      }
    }
  }
}

===

label.background

=== label.background : string Set a custom label background color. Default is #e1edff.

{
  "branding": {
    "colors": {
      "label": {
        "background": "#ff0000"
      }
    }
  }
}

===

cname

=== cname : string

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

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

=== repo : string 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

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

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

===

base

=== base : string 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

=== label : string 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

=== exclude : list 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": [
    "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

=== favicon : string

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": "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

=== copyright : string 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)

=== links : object The footer.links have the same configuration options as links.

{
  "footer": {
    "links": [
      {
        "text": "License",
        "link": "license.md"
      }
    ]
  }
}

===

include

=== include : list 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": [
    "*.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

=== input : string

Custom path to the input directory. Default is ..

The path is relative to the retype.json location.

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

=== googleAnalytics.id : string 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

=== text : string

The link text label.

{
  "links": [
    {
      "text": "Demos",
      "link": "https://demo.example.com/"
    }
  ]
}

===

link

=== link : string

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

=== icon : string

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.

"icon": "rocket"

"icon": ":rocket:"

"icon": "<svg>...</svg>"

"icon": "../static/rocket.png"

===

iconAlign

=== iconAlign : string

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

=== target : string

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`

===

output

=== output : string

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

The path is relative to the retype.json location.

{
  "output": "./docs"
}

===

port

=== port : number

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

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

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

===

maxResults

=== maxResults : number Max number of search results to render. Defualt is 20.

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

===

placeholder

=== placeholder : string Placeholder text rendered on the search component. Defualt is "Search".

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

===

hotkeys

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

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

===

noResultsFoundMsg

=== noResultsFoundMsg : string 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

=== lineNumbers : string[]

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

{
  "snippets": {
    "lineNumbers": [ "js", "json" ]
  }
}

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

{
  "snippets": {
    "lineNumbers": [ "*" ]
  }
}

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

{
  "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`

Files

project.md

Latest commit

History

project.md

File metadata and controls

Project configuration

base

branding

title

label

logo

logoDark

colors

label.text

label.background

cname

edit

repo

branch

base

label

exclude

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

favicon

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

links (footer)

include

input

integrations

googleAnalytics

links

text

link

icon

iconAlign

target

meta

base

title

===

output

port

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

minChars

maxResults

placeholder

hotkeys

noResultsFoundMsg

snippets

lineNumbers

Additional options

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

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.

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.