├── blog ├── blog.md ├── images │ ├── 2025-05-04.png │ ├── 2025-05-28.png │ ├── 2025-06-06.png │ ├── 2025-06-09.png │ ├── 2025-06-10.png │ ├── 2025-07-02-hero.png │ ├── 2025-07-02-themes.png │ ├── 2025-06-09-nextprev.png │ ├── 2025-05-28-nav-icon-mode.png │ ├── 2025-06-10-file-explorer.png │ ├── 2025-07-02-color-scheme.png │ ├── 2025-07-02-search-field.png │ ├── 2025-07-02-navigation-badge.png │ └── 2025-06-10-obsidian-help-repo.png ├── 2025-06-06-new-gitHub-pages-community-key.md ├── 2025-06-09-whats-new-in-retype-v310.md ├── 2025-05-28-whats-new-in-retype-v39.md └── 2025-05-04-whats-new-in-retype-v38.md ├── hosting ├── index.yml ├── heroku-logo.png ├── web-server.md ├── cloudflare.md ├── docker.md ├── gitlab-pages.md ├── netlify.md ├── github-pages.md ├── ftp.md └── heroku.md ├── samples ├── index.yml ├── _includes │ ├── basic-page.md │ ├── page-with-header.png │ └── page-with-header.md ├── hidden.md ├── basic-page.md ├── page-with-header.md ├── private.md ├── protected.md ├── advanced-project-config.md └── basic-project-config.md ├── static ├── sample.txt ├── sample.jpg ├── retype-hero.png ├── sample-large.jpg ├── add-retype-key.png ├── mermaid-header.png ├── hub-screencapture.png ├── powered-by-retype.png ├── retype-hero-old.png ├── retype-hero-pro.png ├── gravatar-sample-mp.png ├── gravatar-sample-retro.png ├── project-branding-title.png ├── retype-repository-key.png ├── add-retype-default-host.png ├── gravatar-sample-robohash.png ├── gravatar-sample-wavatar.png ├── github-actions-enable-pages.png ├── gravatar-sample-identicon.png ├── gravatar-sample-monsterid.png ├── website-configuration-error.png ├── github-actions-configure-branch.png ├── project-base-config-github-pages.png ├── retype-repository-secrets-list.png ├── retype-repository-secrets-list2.png ├── website-configuration-error-dark.png ├── github-actions-configure-custom-domain.png ├── retype-icon.svg ├── styles.css ├── logos │ ├── cloudflare.svg │ ├── gitlab.svg │ ├── netlify.svg │ └── docker.svg ├── retype-logo-dark.svg ├── retype-logo.svg └── sample.js ├── guides ├── index.yml ├── key-setup.md ├── troubleshooting.md ├── getting-started.md ├── formatting.md ├── themes.md └── github-actions.md ├── _includes ├── top.md ├── body.html ├── body-top.html ├── head-top.html ├── head.html ├── snippets │ ├── footer.md │ ├── password-notice.md │ ├── contact-us.md │ ├── support.md │ ├── simple-code-sample.md │ ├── markdown-sample.md │ └── default-pages.md ├── components │ └── octicons.md ├── bottom.md └── data │ └── octicons.md ├── configuration ├── index.yml ├── envvars.md ├── folder.md └── reserved_words.md ├── favicon.ico ├── .gitignore ├── favicon-dark.ico ├── blog-news.md ├── .github └── workflows │ └── retype-action.yml ├── pro └── thankyou.md ├── components ├── emoji.md ├── icon.md ├── components.md ├── octicons.md ├── tab.md ├── file-download.md ├── math-formulas.md ├── comments.md ├── youtube.md ├── column.md ├── embed.md ├── reference-link.md ├── table.md ├── image-alignment-demo.md ├── code-snippet.md ├── panel.md ├── container.md ├── callout.md ├── button.md ├── badge.md ├── image.md └── code-block.md ├── features.md ├── community.md ├── faq.md ├── retype.yml ├── about.md └── README.md /blog/blog.md: -------------------------------------------------------------------------------- 1 | # Blog & News -------------------------------------------------------------------------------- /hosting/index.yml: -------------------------------------------------------------------------------- 1 | icon: server -------------------------------------------------------------------------------- /samples/index.yml: -------------------------------------------------------------------------------- 1 | icon: terminal -------------------------------------------------------------------------------- /static/sample.txt: -------------------------------------------------------------------------------- 1 | This is just a sample .txt document. -------------------------------------------------------------------------------- /guides/index.yml: -------------------------------------------------------------------------------- 1 | order: 1000 2 | icon: book 3 | expanded: true -------------------------------------------------------------------------------- /_includes/top.md: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /configuration/index.yml: -------------------------------------------------------------------------------- 1 | order: 800 2 | icon: gear 3 | expanded: true 4 | -------------------------------------------------------------------------------- /_includes/body.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/favicon.ico -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .retype/ 2 | .DS_Store 3 | /.obsidian 4 | retype.manifest 5 | /templating 6 | -------------------------------------------------------------------------------- /_includes/body-top.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /_includes/head-top.html: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /favicon-dark.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/favicon-dark.ico -------------------------------------------------------------------------------- /static/sample.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/sample.jpg -------------------------------------------------------------------------------- /blog-news.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: rss 3 | redirect: /blog/ 4 | label: Blog & News 5 | order: 1500 6 | --- -------------------------------------------------------------------------------- /hosting/heroku-logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/hosting/heroku-logo.png -------------------------------------------------------------------------------- /static/retype-hero.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/retype-hero.png -------------------------------------------------------------------------------- /static/sample-large.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/sample-large.jpg -------------------------------------------------------------------------------- /static/add-retype-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/add-retype-key.png -------------------------------------------------------------------------------- /static/mermaid-header.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/mermaid-header.png -------------------------------------------------------------------------------- /blog/images/2025-05-04.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-05-04.png -------------------------------------------------------------------------------- /blog/images/2025-05-28.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-05-28.png -------------------------------------------------------------------------------- /blog/images/2025-06-06.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-06-06.png -------------------------------------------------------------------------------- /blog/images/2025-06-09.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-06-09.png -------------------------------------------------------------------------------- /blog/images/2025-06-10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-06-10.png -------------------------------------------------------------------------------- /static/hub-screencapture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/hub-screencapture.png -------------------------------------------------------------------------------- /static/powered-by-retype.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/powered-by-retype.png -------------------------------------------------------------------------------- /static/retype-hero-old.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/retype-hero-old.png -------------------------------------------------------------------------------- /static/retype-hero-pro.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/retype-hero-pro.png -------------------------------------------------------------------------------- /samples/_includes/basic-page.md: -------------------------------------------------------------------------------- 1 | # Welcome! 2 | 3 | This is a basic page, with only a title and some text content. -------------------------------------------------------------------------------- /static/gravatar-sample-mp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/gravatar-sample-mp.png -------------------------------------------------------------------------------- /blog/images/2025-07-02-hero.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-07-02-hero.png -------------------------------------------------------------------------------- /blog/images/2025-07-02-themes.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-07-02-themes.png -------------------------------------------------------------------------------- /static/gravatar-sample-retro.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/gravatar-sample-retro.png -------------------------------------------------------------------------------- /static/project-branding-title.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/project-branding-title.png -------------------------------------------------------------------------------- /static/retype-repository-key.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/retype-repository-key.png -------------------------------------------------------------------------------- /blog/images/2025-06-09-nextprev.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-06-09-nextprev.png -------------------------------------------------------------------------------- /static/add-retype-default-host.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/add-retype-default-host.png -------------------------------------------------------------------------------- /static/gravatar-sample-robohash.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/gravatar-sample-robohash.png -------------------------------------------------------------------------------- /static/gravatar-sample-wavatar.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/gravatar-sample-wavatar.png -------------------------------------------------------------------------------- /samples/_includes/page-with-header.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/samples/_includes/page-with-header.png -------------------------------------------------------------------------------- /static/github-actions-enable-pages.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/github-actions-enable-pages.png -------------------------------------------------------------------------------- /static/gravatar-sample-identicon.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/gravatar-sample-identicon.png -------------------------------------------------------------------------------- /static/gravatar-sample-monsterid.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/gravatar-sample-monsterid.png -------------------------------------------------------------------------------- /static/website-configuration-error.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/website-configuration-error.png -------------------------------------------------------------------------------- /blog/images/2025-05-28-nav-icon-mode.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-05-28-nav-icon-mode.png -------------------------------------------------------------------------------- /blog/images/2025-06-10-file-explorer.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-06-10-file-explorer.png -------------------------------------------------------------------------------- /blog/images/2025-07-02-color-scheme.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-07-02-color-scheme.png -------------------------------------------------------------------------------- /blog/images/2025-07-02-search-field.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-07-02-search-field.png -------------------------------------------------------------------------------- /blog/images/2025-07-02-navigation-badge.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-07-02-navigation-badge.png -------------------------------------------------------------------------------- /static/github-actions-configure-branch.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/github-actions-configure-branch.png -------------------------------------------------------------------------------- /static/project-base-config-github-pages.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/project-base-config-github-pages.png -------------------------------------------------------------------------------- /static/retype-repository-secrets-list.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/retype-repository-secrets-list.png -------------------------------------------------------------------------------- /static/retype-repository-secrets-list2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/retype-repository-secrets-list2.png -------------------------------------------------------------------------------- /static/website-configuration-error-dark.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/website-configuration-error-dark.png -------------------------------------------------------------------------------- /blog/images/2025-06-10-obsidian-help-repo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/blog/images/2025-06-10-obsidian-help-repo.png -------------------------------------------------------------------------------- /_includes/head.html: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /static/github-actions-configure-custom-domain.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/retypeapp/retype/HEAD/static/github-actions-configure-custom-domain.png -------------------------------------------------------------------------------- /_includes/snippets/footer.md: -------------------------------------------------------------------------------- 1 | © Copyright {{ date.now.year }} - [Retype](https://retype.com/) | All rights reserved | Made in Canada :flag-ca: | v{{ version }} -------------------------------------------------------------------------------- /samples/_includes/page-with-header.md: -------------------------------------------------------------------------------- 1 | ![](page-with-header.png) 2 | 3 | # Page with header 4 | 5 | This is a page with a top feature image as the header. -------------------------------------------------------------------------------- /_includes/components/octicons.md: -------------------------------------------------------------------------------- 1 | | Icon | Shortcode | Sample | 2 | | :---: | --- | --- | 3 | {{~ for $i in $.list ~}} 4 | | :icon-{{ $i }}: | {{ $i }} | `:icon-{{ $i }}:` | 5 | {{~ end ~}} -------------------------------------------------------------------------------- /_includes/bottom.md: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | {{~ for item in abbreviations ~}} 5 | *[{{ item.key }}]: {{ item.value }} 6 | {{~ end ~}} -------------------------------------------------------------------------------- /static/retype-icon.svg: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /static/styles.css: -------------------------------------------------------------------------------- 1 | blockquote.callout, .dark blockquote.callout { 2 | font-size: 1.875rem; 3 | font-weight: 500; 4 | text-align: center; 5 | background-color: transparent; 6 | border-left-width: 0; 7 | line-height: 1.5em; 8 | } -------------------------------------------------------------------------------- /samples/hidden.md: -------------------------------------------------------------------------------- 1 | --- 2 | visibility: hidden 3 | --- 4 | # Hidden page 5 | 6 | This page will be hidden from the menu and search results. 7 | 8 | The password is `test`. 9 | 10 | See [`visibility`](/configuration/page.md#visibility) documentation. -------------------------------------------------------------------------------- /samples/basic-page.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: file 3 | data: 4 | title: basic-page.md 5 | path: _includes/basic-page.md 6 | --- 7 | {{ include path }} 8 | 9 | --- 10 | 11 | ## :icon-code: Source 12 | 13 | [!file Download]({{ path }}) 14 | 15 | :::code source="{{ path }}" title="{{ title }}" ::: 16 | -------------------------------------------------------------------------------- /_includes/snippets/password-notice.md: -------------------------------------------------------------------------------- 1 | !!! 2 | Only one password can be configured per project. The password protection functionality within Retype is not designed to be a comprehensive security layer with features such as multiple accounts or roles. Only the most basic password protection for pages is enabled. 3 | !!! -------------------------------------------------------------------------------- /samples/page-with-header.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: file 3 | data: 4 | title: page-with-header.md 5 | path: _includes/page-with-header.md 6 | --- 7 | {{ include path }} 8 | 9 | --- 10 | 11 | ## :icon-code: Source 12 | 13 | [!file Download]({{ path }}) 14 | 15 | :::code source="{{ path }}" title="{{ title }}" ::: -------------------------------------------------------------------------------- /_includes/snippets/contact-us.md: -------------------------------------------------------------------------------- 1 | Please feel free to contact us any time: 2 | 3 | - [x] Start a new [Issue](https://github.com/retypeapp/retype/issues/), or 4 | - [x] Email hello@retype.com, or 5 | - [x] Send a tweet to [@retypeapp](https://twitter.com/retypeapp) 6 | - [x] Online chat, see :icon-comment: button in bottom right corner -------------------------------------------------------------------------------- /_includes/snippets/support.md: -------------------------------------------------------------------------------- 1 | ## Support 2 | 3 | Do you have a technical support question, find a defect, or would like to make a feature request? Please create an [issue](https://github.com/retypeapp/retype/issues) to get the conversation started. 4 | 5 | Do you have a general inquiry? Please feel free to contact us at hello@retype.com. 6 | 7 | We :heart: your feedback. -------------------------------------------------------------------------------- /samples/private.md: -------------------------------------------------------------------------------- 1 | --- 2 | visibility: private 3 | --- 4 | # Private page 5 | 6 | This page will not be visible in the main navigation and will require a password to view the page. 7 | 8 | The password is `test`. 9 | 10 | See [`visibility`](/configuration/page.md#visibility) documentation. 11 | 12 | ## :icon-code: Source 13 | 14 | :::code source="private.md" ::: -------------------------------------------------------------------------------- /samples/protected.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: file 3 | visibility: protected 4 | --- 5 | # Protected page 6 | 7 | This page will be visible in the main navigation, but will require a password to view the page. 8 | 9 | The password is `test`. 10 | 11 | See [`visibility`](/configuration/page.md#visibility) documentation. 12 | 13 | ## :icon-code: Source 14 | 15 | :::code source="protected.md" ::: -------------------------------------------------------------------------------- /_includes/snippets/simple-code-sample.md: -------------------------------------------------------------------------------- 1 | export function calculateOffset(): number { 2 | const siteHeaderEl = document.getElementById("docs-site-header"); 3 | const toolbarEl = document.getElementById("docs-toolbar"); 4 | 5 | let offset = 20; // 20 is extra offset added before the focused element 6 | offset += siteHeaderEl ? siteHeaderEl.offsetHeight : 0; 7 | offset += toolbarEl ? toolbarEl.offsetHeight : 0; 8 | 9 | return -offset; 10 | } -------------------------------------------------------------------------------- /samples/advanced-project-config.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: file 3 | order: 900 4 | --- 5 | # Advanced project config 6 | 7 | The following **retype.yml** sample includes all possible [project configuration](/configuration/project.md) options. 8 | 9 | [!file Download retype.yml](/static/retype.yml) 10 | 11 | :::code source="/static/retype.yml" title="retype.yml" ::: 12 | 13 | !!! 14 | All configurations are optional. If a config is not set, Retype will use default values. 15 | !!! -------------------------------------------------------------------------------- /_includes/snippets/markdown-sample.md: -------------------------------------------------------------------------------- 1 | # Welcome! 2 | 3 | This is a paragraph. 4 | 5 | Both [internal](README.md) and [external](https://example.com) links work. 6 | 7 | ![Your logo](logo.png) 8 | 9 | Another paragraph with **bold**, _italic_, ~~strikethrough~~, and `code` samples. 10 | 11 | --- 12 | 13 | ## Lists 14 | 15 | - First item 16 | - Second item 17 | - Third item 18 | 19 | 1. First item 20 | 2. Second item 21 | 3. Third item 22 | 23 | > "Cool! This is a quotation." 24 | 25 | !!! 26 | Need to draw attention to something? Use an alert. 27 | !!! -------------------------------------------------------------------------------- /.github/workflows/retype-action.yml: -------------------------------------------------------------------------------- 1 | name: Publish Retype powered website to GitHub Pages 2 | on: 3 | workflow_dispatch: 4 | push: 5 | branches: 6 | - main 7 | 8 | jobs: 9 | publish: 10 | name: Publish to retype branch 11 | 12 | runs-on: ubuntu-latest 13 | permissions: 14 | contents: write 15 | 16 | steps: 17 | - uses: actions/checkout@v4 18 | 19 | - uses: retypeapp/action-build@next 20 | env: 21 | RETYPE_KEY: ${{ secrets.RETYPE_KEY }} 22 | RETYPE_PASSWORD: ${{ secrets.RETYPE_PASSWORD }} # The password is: test 23 | 24 | - uses: retypeapp/action-github-pages@latest 25 | with: 26 | update-branch: true -------------------------------------------------------------------------------- /hosting/web-server.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: page 3 | icon: server 4 | --- 5 | # Web server 6 | 7 | Retype can be hosted on any web server that allows you to host static website files such as **.html**, **.js**, **.css**, and images. That pretty much includes 100% of the website hosting solutions available, including all shared hosting services. 8 | 9 | FTP the contents of the [`output`](/configuration/project.md#output) folder to your web server. By default, the `output` location should be the `.retype` folder within in the root of your project. 10 | 11 | From Retype's perspective, no other configuration is required. Your entire Retype generated website is self contained. No special server-side technologies are required. Just the ability to host static website files. -------------------------------------------------------------------------------- /samples/basic-project-config.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: file 3 | order: 1000 4 | --- 5 | # Basic project config 6 | 7 | The following is a basic **retype.yml** [project configuration](/configuration/project.md) file. 8 | {%{ 9 | ```yml retype.yml 10 | input: . 11 | output: .retype 12 | 13 | url: docs.example.com # Use your website address here 14 | 15 | start: 16 | # Uncomment the next line to try Retype Pro features 17 | # pro: true 18 | 19 | branding: 20 | title: Project Name 21 | label: Docs 22 | 23 | links: 24 | - text: Getting Started 25 | link: https://retype.com/guides/getting-started/ 26 | 27 | footer: 28 | copyright: "© Copyright {{ year }}. All rights reserved." 29 | ``` 30 | }%} 31 | !!! 32 | All settings are optional. If a setting is not set, Retype will use default values. 33 | !!! -------------------------------------------------------------------------------- /_includes/snippets/default-pages.md: -------------------------------------------------------------------------------- 1 | Folder default pages are **.md** files that will be treated as the index (default) page of the folder. 2 | 3 | Retype will search using the following case insensitive priority: 4 | 5 | 1. `index.md` 6 | 2. `readme.md` 7 | 3. `default.md` 8 | 4. `welcome.md` *only in the project root 9 | 5. `home.md` *only in the project root 10 | 11 | Within a sub-folder, if you add a Markdown **.md** file with the exact same name as the folder name, Retype will also treat that `.md` as a default page. For instance, given the following basic project structure, the **/sample/sample.md** file will function as a default page for the folder. The result will be the same as though you named it **/sample/index.md**: 12 | 13 | ``` 14 | sample 15 | |-- sample.md 16 | readme.md 17 | retype.yml 18 | ``` -------------------------------------------------------------------------------- /pro/thankyou.md: -------------------------------------------------------------------------------- 1 | --- 2 | visibility: hidden 3 | --- 4 | # Thank You! 5 | 6 | Thank you so much for purchasing **Retype Pro**. We really appreciate your support. 7 | 8 | !!!danger 9 | Please check your Spam folder for emails. 10 | !!! 11 | 12 | ## Next steps 13 | 14 | 1. Did you receive your email receipt? If no, please [let us know](mailto:hello@retype.com). 15 | 2. Create your key...\ 16 | [!button text="Create key" icon="plus"](https://docs.google.com/forms/d/e/1FAIpQLSfFWUKHtuyz43MCzBzfFftq3OYt282wbiOfWAmuNz8x2ktxnw/viewform) 17 | 3. Need any additional help with Retype? If yes, see the [next section](#i-need-assistance). 18 | 19 | !!! 20 | We apologize in advance, but we do not yet have a system in place to auto-generate the keys, so anticipate a short delay before receiving your keys by email. 21 | !!! 22 | 23 | ## I need assistance 24 | 25 | Okay, no problem. We are here to help. 26 | 27 | {{ include "snippets/contact-us" }} 28 | -------------------------------------------------------------------------------- /static/logos/cloudflare.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /components/emoji.md: -------------------------------------------------------------------------------- 1 | --- 2 | {{ include "data/emojis" }} 3 | icon: ":grinning:" 4 | tags: [component, icon] 5 | --- 6 | # Emoji 7 | 8 | Retype uses [Mojee](https://mojeeio.github.io/Mojee/) to find emoji `:shortcodes:` within your document and replace with actual emoji characters. :+1: 9 | 10 | You can place emoji `:shortcodes:` anywhere within your document, such as `:smile:` :smile: or `:unicorn_face:` :unicorn_face:. 11 | 12 | Below you’ll find all available emojis, their shortcodes, aliases, descriptions, and related tags. 13 | 14 | Emoji count: **{{ emojis.size }}** 15 | 16 | {.compact} 17 | | Emoji | Shortcode | Description | Tags | 18 | | :---: | --- | --- | --- | 19 | {{~ for $i in emojis ~}} 20 | | :{{ $i.shortcode }}: | `:{{ $i.shortcode }}:` {{ if $i.aliases && $i.aliases.size > 0 }}{{ for $alias in $i.aliases }}
`:{{ $alias }}:`{{ if for.last == false }}, {{ end }}{{ end }}{{ end }} | {{ $i.description }} | {{ $i.tags | array.join ", " }} 21 | {{~ end ~}} -------------------------------------------------------------------------------- /components/icon.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: smiley 3 | tags: [component, icon] 4 | --- 5 | # Icon 6 | 7 | Similar to the [Emoji](emoji.md) `:shortcode:` syntax, you can add icons using `:icon-shortcode:`, where the `shortcode` is an [Octicon](/components/octicons.md) icon name. 8 | 9 | For example, to add the :icon-star: `star` icon, use the `:icon-star:` icon shortcode. 10 | 11 | Icons can be added anywhere within your document, including paragraph text, headings, table content, [Panel](panel.md) component titles, [Callouts](callout.md), [code block](code-block.md) titles, etc. :icon-thumbsup: 12 | 13 | Some icon shortcode names are made up of `two-or-more` words. For instance, the :icon-git-branch: `git-branch` icon would be configured as `:icon-git-branch:`. 14 | 15 | !!! More icons :icon-heart: 16 | In future releases of Retype, the plan is to support additional Icon packs and possibily even custom developer defined icon packs. [Let us know](https://github.com/retypeapp/retype/issues/) if you are interested! 17 | !!! 18 | -------------------------------------------------------------------------------- /features.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: star 3 | visibility: hidden 4 | --- 5 | # Features 6 | 7 | 8 | Feature | [Retype](https://retype.com/) | 9 | -- | -- | 10 | Auto-generate sitemap | :icon-check-circle: | 11 | Auto-generate RSS feed for Blog | :icon-check-circle: | 12 | Auto-generate robots.txt | :icon-check-circle: | 13 | Custom summary pages for `/blog`, `/tags`, and `/categories` | :icon-check-circle: | 14 | Open Graph and Twitter meta tags | :icon-check-circle: | 15 | Auto-detection of content languages | :icon-check-circle: | 16 | Multi-language search | :icon-check-circle: | 17 | [KaTeX](/components/math-formulas.md) math formulas | :icon-check-circle: | 18 | [Mermaid](/components/mermaid.md) diagram and charting tool | :icon-check-circle: | 19 | [Gravatar](/configuration/project.md#gravatar) support on [`author`](/configuration/page.md#author) | :icon-check-circle: | 20 | Lightning fast incremental builds using page dependency graph | :icon-check-circle: | 21 | Active and engaged development team | :icon-check-circle: | -------------------------------------------------------------------------------- /static/logos/gitlab.svg: -------------------------------------------------------------------------------- 1 | 2 | 3 | -------------------------------------------------------------------------------- /static/retype-logo-dark.svg: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /static/retype-logo.svg: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /static/sample.js: -------------------------------------------------------------------------------- 1 | // Simple calculator app 2 | // https://github.com/JS-Beginners/Calculator-JavaScript-Project 3 | (function () { 4 | 5 | let screen = document.querySelector(".screen"); 6 | let buttons = document.querySelectorAll(".btn"); 7 | let clear = document.querySelector(".btn-clear"); 8 | let equal = document.querySelector(".btn-equal"); 9 | 10 | // retrieve data from numbers that are clicked 11 | buttons.forEach(function (button) { 12 | button.addEventListener("click", function (e) { 13 | let value = e.target.dataset.num; 14 | screen.value += value; 15 | }) 16 | }); 17 | 18 | equal.addEventListener("click", function (e) { 19 | if (screen.value === "") { 20 | screen.value = "Please Enter a Value"; 21 | } else { 22 | let answer = eval(screen.value); 23 | screen.value = answer; 24 | } 25 | }) 26 | 27 | clear.addEventListener("click", function (e) { 28 | screen.value = ""; 29 | }) 30 | 31 | })(); -------------------------------------------------------------------------------- /components/components.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: tools 3 | backlinks: 4 | enabled: false 5 | --- 6 | # Components 7 | 8 | Retype Flavored [Markdown](/guides/formatting.md) (RFM) supports custom **Components**, including: 9 | 10 | | Text | Layout | Code | 11 | | -- | -- | -- | 12 | | [:icon-id-badge: Badge](badge.md) | [:icon-columns: Column](column.md) | [:icon-code-square: Code Block](code-block.md) | 13 | | [:+1: Emoji](emoji.md) | [:icon-container: Container](container.md) | [:icon-code: Code Snippet](code-snippet.md) | 14 | | [:icon-smiley: Icon](icon.md) | [:icon-rows: Panel](panel.md) | [:icon-diff-added: Math Formulas](math-formulas.md) | 15 | | [:icon-mark-github: Octicons](octicons.md) | [:icon-browser: Tab](tab.md) | [:mermaid: Mermaid](mermaid.md) | 16 | | [:icon-code-review: Comments](comments.md) | | | 17 | 18 | | Lists | Media | Interactive | 19 | | -- | -- | -- | 20 | | [:icon-list-unordered: List](list.md) | [:icon-image: Image](image.md) | [:icon-play: Button](button.md) 21 | | [:icon-table: Table](table.md) | [:icon-download: File Download](file-download.md) | [:icon-info: Callout](callout.md) 22 | | | [:icon-video: YouTube](youtube.md) | [:icon-link: Reference Link](reference-link.md) 23 | | | [:icon-code-review: Embed](embed.md) | | -------------------------------------------------------------------------------- /guides/key-setup.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 500 3 | icon: key 4 | --- 5 | # Key setup 6 | 7 | There are 3 different ways you can add a key to your project: 8 | 9 | ## Option 1: Use `retype wallet` 10 | 11 | To use the key on your local development computer, run the following command and replace the `` with your Retype Key. 12 | 13 | ``` 14 | retype wallet --add 15 | ``` 16 | 17 | !!! 18 | See more details regarding the [`retype wallet`](/guides/cli.md#retype-wallet) command. 19 | !!! 20 | 21 | --- 22 | 23 | ## Option 2: `--key` command line flag 24 | 25 | You can pass the key as a command line option by calling: 26 | 27 | ``` 28 | retype build --key 29 | ``` 30 | 31 | !!! 32 | See more details regarding the [`retype build`](/guides/cli.md#retype-build) command. 33 | !!! 34 | 35 | --- 36 | 37 | ## Option 3: `RETYPE_KEY` environment variable 38 | 39 | The key can be added as an [Environment Variable](/configuration/envvars.md), which is recommended for building and hosting on services such as [[GitHub Pages]], [[Netlify]], and [[Cloudflare]]. 40 | 41 | Then add `RETYPE_KEY` secret to your [[GitHub Actions]] file: 42 | 43 | {%{ 44 | ``` 45 | - uses: retypeapp/action-build@latest 46 | with: 47 | key: ${{ secrets.RETYPE_KEY }} 48 | ``` 49 | }%} 50 | -------------------------------------------------------------------------------- /hosting/cloudflare.md: -------------------------------------------------------------------------------- 1 | --- 2 | label: Cloudflare 3 | icon: /static/logos/cloudflare.svg 4 | tags: [guide,hosting] 5 | author: TiagoVXII # Big thanks to TiagoVXII for writing this hosting guide 6 | --- 7 | # Cloudflare Pages 8 | 9 | [Cloudflare](https://www.cloudflare.com/) is a popular website used to host your websites and protect them, It's used by millions of people also using Retype. 10 | 11 | ## Step 1: Add retype-action.yml workflow 12 | 13 | We first recommend adding the [Retype GitHub Build Action](https://retype.com/guides/github-actions/#step-1-add-retype-actionyml-workflow) to your project to automate the building and deployment of your Retype powered website. 14 | 15 | ## Step 2: Signup for Cloudflare 16 | 17 | 1. Go to the Cloudflare website at [cloudflare.com](https://www.cloudflare.com/) 18 | 2. Click on **Sign up** on the top right of the page and follow the instructions 19 | 4. After sign up, you will have access to your Cloudflare dashboard 20 | 21 | ## Step 3: Create a new page 22 | 23 | 1. Once in the dashboard, scroll down until you see **Pages** 24 | 2. Click on **Create a project** 25 | 3. Click on **Connect to Git** 26 | 4. Follow the instruction and choose your repository 27 | 5. Choose your project name and by default that will be the website name 28 | 6. Choose production branch as `retype`, but please ensure you have completed [Step 1](#step-1-add-retype-actionyml-workflow) above first 29 | 7. Save and deploy 30 | 8. Give Cloudflare a few moments and your website will be online :+1: 31 | -------------------------------------------------------------------------------- /static/logos/netlify.svg: -------------------------------------------------------------------------------- 1 | 2 | -------------------------------------------------------------------------------- /components/octicons.md: -------------------------------------------------------------------------------- 1 | --- 2 | {{ include "data/octicons" }} 3 | icon: mark-github 4 | --- 5 | # Octicons 6 | 7 | [Octicons](https://primer.github.io/octicons/) can be used with the [Icon](icon.md) component and several other components, including the [Badge](badge.md) and [Button](button.md). 8 | 9 | ## Samples 10 | 11 | ### Component 12 | 13 | For the [Icon](icon.md) component, the icon is specified using the syntax `:icon-shortcode:`, where `shortcode` is the name of the icon (found in the table below). 14 | 15 | For example, use the code `:icon-rocket:` for a :icon-rocket: icon. 16 | 17 | When an icon is used in other components, the icon is referred to by only the `shortcode`. 18 | 19 | For example, the following demonstrates using the icon in a [Badge](badge.md#icon-and-emoji) and a [Button](button.md#icon-and-emoji). 20 | 21 | Component | Sample 22 | --- | --- 23 | [!badge icon="rocket" text="rocket"] | `[!badge icon="rocket" text="rocket"]` 24 | [!button icon="rocket" text="rocket"] | `[!button icon="rocket" text="rocket"]` 25 | 26 | ### Metadata 27 | 28 | When an icon is specified within the [Page](../configuration/page.md) or [Project](../configuration/project.md) metadata, the icon can be referred to by only its `shortcode`. 29 | 30 | The following sample demonstrates setting a Page [icon](../configuration/page.md/#icon) to a :icon-rocket:. 31 | 32 | ``` 33 | --- 34 | icon: rocket 35 | --- 36 | # Sample 37 | 38 | This is a sample page with a :icon-rocket: icon. 39 | ``` 40 | 41 | ## New icons 42 | 43 | The following [!badge NEW|info] icons are included in Retype **v{{ version }}**: 44 | 45 | {{ include "components/octicons" list:octicons_new }} 46 | 47 | ## All icons 48 | 49 | As of v{{ version }}, there are {{ octicons.size }} [Octicons](https://primer.github.io/octicons/) supported and more being added with each new release. 50 | 51 | {{ include "components/octicons" list:octicons }} 52 | -------------------------------------------------------------------------------- /components/tab.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: browser 3 | tags: [component] 4 | --- 5 | # Tab 6 | 7 | With Retype, a Tab component is super simple to configure by surrounding a block of text with `+++` and including a title for the tab. 8 | 9 | ```md 10 | +++ Tab 1 11 | This is a Tab 12 | +++ 13 | ``` 14 | 15 | +++ Tab 1 16 | This is a Tab 17 | +++ 18 | 19 | The tab `title` must be separated from the opening `+++` by one space. The pattern `+++ Tab ` will work as expected, and `+++Tab 1` will not. 20 | 21 | --- 22 | 23 | ## Multiple tabs 24 | 25 | Multiple Tabs can be configured by stacking multiple `+++` blocks and adding a title for each tab. 26 | 27 | ```md 28 | +++ Tab 1 29 | This is a Tab 30 | +++ Tab 2 31 | This is another Tab 32 | +++ Tab 3 33 | Wow! Yet another tab :+1: 34 | +++ 35 | ``` 36 | 37 | +++ Tab 1 38 | This is a Tab 39 | +++ Tab 2 40 | This is another Tab 41 | +++ Tab 3 42 | Wow! Yet another tab :+1: 43 | +++ 44 | 45 | --- 46 | 47 | ## Empty lines 48 | 49 | Extra empty lines at the start or end of the Tab are allowable, although ignored. Tabs can contain any number of leading or trailing empty lines. 50 | 51 | ```md 52 | +++ Tab 1 53 | 54 | This is a Tab 55 | 56 | +++ Tab 2 57 | This is another Tab 58 | +++ Tab 3 59 | 60 | Wow! Yet another tab :+1: 61 | 62 | +++ 63 | ``` 64 | 65 | +++ Tab 1 66 | 67 | This is a Tab 68 | 69 | +++ Tab 2 70 | This is another Tab 71 | +++ Tab 3 72 | 73 | Wow! Yet another tab :+1: 74 | 75 | +++ 76 | 77 | --- 78 | 79 | ## Anchors 80 | 81 | Each Tab is an anchor that allows for linking directly to the tab by passing the anchor in a URL. 82 | 83 | If the tab anchor is passed in the URL, when the page loads, the page will be automatically scrolled to that tab position and the tab will be selected. 84 | 85 | To get the tab URL with the anchor, right-click on the tab and select `Copy Link Address`. 86 | 87 | ```md 88 | [Tab anchor link](#tab-3) 89 | ``` 90 | 91 | [Tab anchor link](#tab-3) 92 | -------------------------------------------------------------------------------- /static/logos/docker.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /guides/troubleshooting.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: alert 3 | nav: 4 | badge: NEW|info 5 | tags: [guide, pro] 6 | --- 7 | # Troubleshooting 8 | 9 | If you encounter issues while using Retype, this guide will help you identify and resolve common problems quickly. Follow the steps below to troubleshoot and get your project back on track. 10 | 11 | !!!danger 12 | Please ensure your Retype Pro key is licensed for your project [`url`](/configuration/project.md#url). 13 | !!! 14 | 15 | ## Website Configuration Error 16 | 17 | If you encounter the **Website Configuration Error** message, please ensure your [Retype Pro](/pro/pro.md) key is valid for the same [`url`](/configuration/project.md#url) that is set in your project `retype.yml` configuration file. 18 | 19 | ![](/static/website-configuration-error.png) 20 | 21 | Common scenarios that would trigger this error: 22 | 23 | 1. You are hosting a website built with a Retype Pro key but do not have the project [`url`](/configuration/project.md#url) set 24 | 1. You are hosting a website built with a Retype Pro key but the project [`url`](/configuration/project.md#url) is set to a url that is not supported by the Pro key 25 | 1. The `config.js` file has been modified 26 | 1. The `retype.css` file has been modified 27 | 28 | If you see this error and are confident your Pro key and `url` are correctly configured, please send an email to hello@retype.com and we will investigate immediately. 29 | 30 | ## Secret is not valid 31 | 32 | The error below is also likely triggered by the same configuration issue as the error above. If you see the following **secret is not valid** error, the project [`url`](/configuration/project.md#url) is set to a value that is not valid for the Retype Pro key the project is using. 33 | 34 | ``` 35 | ERROR: The specified secret is not valid for the "url" config host: "example.com". 36 | ``` 37 | 38 | If you see this error and are confident your Pro key and `url` are correctly configured, please send an email to hello@retype.com and we will investigate immediately. -------------------------------------------------------------------------------- /components/file-download.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: download 3 | tags: [component] 4 | --- 5 | # File Download 6 | 7 | A static file download component can be configured by using the `!file` specifier in a link. 8 | 9 | ```md 10 | [!file](/static/sample.txt) 11 | ``` 12 | 13 | [!file](/static/sample.txt) 14 | 15 | --- 16 | 17 | ## Custom text 18 | 19 | By default, the text of the file download component is not required. Retype will automatically use the file name as the text. 20 | 21 | The text can be explicitly set by passing as the first part of the component config. In the following sample, we explicitly set the text to `Sample`. 22 | 23 | ```md 24 | [!file Sample](/static/sample.txt) 25 | ``` 26 | 27 | [!file Sample](/static/sample.txt) 28 | 29 | Clicking anywhere within the file download component will trigger the web browser to download the static file. 30 | 31 | --- 32 | 33 | ## Custom icon 34 | 35 | The `icon` used for the file download component can be customized using a name/value pair syntax for the `text` and `icon` attributes. This allows for setting a custom `icon` and `text` value at the same time. The `icon` attribute can be initialize with one of the following: 36 | - [Octicon](/components/octicons.md) name 37 | - Emoji `:shortcode:` (please see [Mojee](https://mojeeio.github.io/Mojee//emojis) for a full list of supported Emoji shortcodes) 38 | - Image file URL 39 | 40 | The following samples demonstrate setting a custom `icon`: 41 | 42 | ``` 43 | [!file icon="rocket"](/static/sample.txt) 44 | [!file icon=":rocket:"](/static/sample.txt) 45 | [!file icon="../static/retype-icon.svg"](/static/sample.txt) 46 | ``` 47 | 48 | [!file icon="rocket"](/static/sample.txt) 49 | [!file icon=":rocket:"](/static/sample.txt) 50 | [!file icon="../static/retype-icon.svg"](/static/sample.txt) 51 | 52 | By default, the file name is used as the component text value and the text can be customized by explicitly passing a separate `text` value. 53 | 54 | ``` 55 | [!file icon="rocket" text="To the moon"](/static/sample.txt) 56 | ``` 57 | 58 | [!file icon="rocket" text="To the moon"](/static/sample.txt) 59 | -------------------------------------------------------------------------------- /community.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: people 3 | order: 1200 4 | tags: 5 | - community 6 | - github 7 | label: Community #[NEW] 8 | nav: 9 | badge: NEW|info 10 | --- 11 | # Community 12 | 13 | ## Keys 14 | 15 | ### GitHub Pages 16 | 17 | With the community key, you can now setup your project to be hosted using **GitHub Pages** and unlock **Retype Pro** features. 18 | 19 | Please see the [announcement](/blog/2025-06-06-new-gitHub-pages-community-key.md), [[GitHub Pages]] setup, and Retype [[Key setup]] instructions. 20 | 21 | ``` 22 | dEVPBhEAT01MR0NBQ0xBT0VHR0NDR0dGT09PRUFDTEZARE9PT09FRERET15aEx0AHAEWWh0bT0Q-pId4N7uwS11nfzalpH2MG9Wql5Jtoc9vFnQMJJeh0WfKhv7CHrYPeg 23 | ``` 24 | 25 | Add the above [[community]] key to your [Retype Wallet](/guides/cli.md#retype-wallet) using the `retype wallet --add ` command. The command below includes the full `` making it easy to copy/paste: 26 | 27 | ``` 28 | retype wallet --add dEVPBhEAT01MR0NBQ0xBT0VHR0NDR0dGT09PRUFDTEZARE9PT09FRERET15aEx0AHAEWWh0bT0Q-pId4N7uwS11nfzalpH2MG9Wql5Jtoc9vFnQMJJeh0WfKhv7CHrYPeg 29 | ``` 30 | 31 | Please review all options for [[key setup]]. 32 | 33 | ## :icon-heart: Sponsors 34 | 35 | Can your organization purchase a Retype [Enterprise](/pro/pro.md) key for any of the following hosting services? If yes, the Retype community would love you and we can list your organization in the Community page as the sponsor. 36 | 37 | Feel free to [contact us](mailto:hello@retype.com) if you have any questions or other community sponsorship proposals. 38 | 39 | {.whitespace-nowrap} 40 | Service | Domain | :icon-heart: Sponsor 41 | --- | --- | --- 42 | [[GitHub Pages]] | `*.github.io` | [Retype](https://retype.com) 43 | [AWS CloudFront](https://aws.amazon.com/cloudfront/) | `*.cloudfront.net` | 44 | [CloudFlare Pages](/hosting/cloudflare.md) | `*.pages.dev` | 45 | [GitLab Pages](/hosting/gitlab-pages.md) | `*.gitlab.io` | 46 | [Google Firebase](https://firebase.google.com/) | `*.web.app` and
`*.firebaseapp.com` | 47 | [[Netlify]] | `*.netlify.app` | 48 | [Render](https://render.com/) | `*.onrender.com` | 49 | [Vercel](https://vercel.com/) | `*.vercel.app` | -------------------------------------------------------------------------------- /hosting/docker.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: /static/logos/docker.svg 3 | tags: 4 | - guide 5 | - hosting 6 | --- 7 | # Docker 8 | 9 | Using a docker container has numerous advantages, including: 10 | 11 | - Effortless deployments on [Heroku](https://devcenter.heroku.com/categories/deploying-with-docker), [Amazon ECS](https://docs.docker.com/cloud/ecs-integration/), or [Google Cloud Engine](https://cloud.google.com/compute/docs/containers) 12 | - Highly secure yet highly scalable to meet any hosting requirements 13 | - Portability which allows for moving hosting environments efficiently 14 | 15 | ## Step 1: Add a `Dockerfile` to your project 16 | 17 | First step is to create a Dockerfile in your project. 18 | 19 | The following sample `Dockerfile` will build the Retype project and create a `httpd` image based container as the output. 20 | 21 | ```dockerfile # Dockerfile 22 | FROM mcr.microsoft.com/dotnet/sdk:9.0 AS builder 23 | WORKDIR /build 24 | COPY . /build 25 | RUN dotnet tool install retypeapp --tool-path /bin 26 | RUN retype build --output .docker-build/ 27 | 28 | FROM httpd:latest 29 | COPY --from=builder /build/.docker-build/ /usr/local/apache2/htdocs/ 30 | ``` 31 | 32 | ## Step 2: Build the image 33 | 34 | !!! 35 | Most cloud platforms can build the image on their own. See their corresponding documentation for more information. 36 | !!! 37 | 38 | After creating the Dockerfile you can use your local Docker instance to build the image with the following command: 39 | 40 | ```bash # 41 | docker build -t myorg/myapplication:latest . 42 | ``` 43 | 44 | To confirm that the build worked, run the container locally with: 45 | 46 | ```bash # 47 | docker run --rm -p 8080:80 myorg/myapplication:latest 48 | ``` 49 | 50 | You should be able to now open a web browser and browse to your IP address on port `8080`. If running locally, [localhost:8080](http://localhost:8080) should work. 51 | 52 | ## Step 3: Publish the Image 53 | 54 | After building your docker container, you can publish the container to any free-to-use repository such as [Docker Hub](https://hub.docker.com/). See the Docker Hub [docs](https://docs.docker.com/docker-hub/) for more details. 55 | -------------------------------------------------------------------------------- /components/math-formulas.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: diff-added 3 | tags: [component] 4 | --- 5 | # Math Formulas 6 | 7 | Retype supports rendering math formulas written according to the [LaTeX](https://en.wikipedia.org/wiki/LaTeX) grammar. Internally, Retype is powered by [$\KaTeX$](https://katex.org/) and supports all syntax of the library. 8 | 9 | Math equations can be rendered inline by wrapping the equation in `$` characters, or as separate blocks by fencing the equation in `$$` characters. 10 | 11 | ## Inline syntax 12 | 13 | An inline math equation is wrapped in `$` characters. 14 | 15 | ```latex Inline formula 16 | $\displaystyle \left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$ 17 | ``` 18 | 19 | This formula $\displaystyle \left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$ is inlined with text. 20 | 21 | --- 22 | 23 | ## Block syntax 24 | 25 | A block math equation is wrapped with `$$` characters. Block equations are center aligned when rendered to the finished page. 26 | 27 | ```latex The $$ multiline formula block 28 | $$ 29 | \displaystyle {1 + \frac{q^2}{(1-q)}+\frac{q^6}{(1-q)(1-q^2)}+\cdots }= \prod_{j=0}^{\infty}\frac{1}{(1-q^{5j+2})(1-q^{5j+3})}, \quad\quad \text{for }\lvert q\rvert<1. 30 | $$ 31 | ``` 32 | 33 | $$ 34 | \displaystyle {1 + \frac{q^2}{(1-q)}+\frac{q^6}{(1-q)(1-q^2)}+\cdots }= \prod_{j=0}^{\infty}\frac{1}{(1-q^{5j+2})(1-q^{5j+3})}, \quad\quad \text{for }\lvert q\rvert<1. 35 | $$ 36 | 37 | --- 38 | 39 | ## LaTeX code highlighting 40 | 41 | Math formula blocks can benefit from syntax highlighting by adding the `latex` language specifier to code blocks. 42 | 43 | ||| Demo 44 | 45 | ```latex 46 | \bigg\{ \;\mathbb{F}[x]\text{-modules } V\; \bigg\} 47 | \longleftrightarrow 48 | \bigg\{ \substack{\text{$\mathbb{F}$-vector spaces $V$ with a} 49 | \\ \text{linear map $T : V \rightarrow V$}} \bigg\} 50 | 51 | 52 | 53 | ``` 54 | 55 | ||| Source 56 | 57 | ~~~ 58 | ```latex 59 | \bigg\{ \;\mathbb{F}[x]\text{-modules } V\; \bigg\} 60 | \longleftrightarrow 61 | \bigg\{ \substack{\text{$\mathbb{F}$-vector spaces $V$ with a} 62 | \\ \text{linear map $T : V \rightarrow V$}} \bigg\} 63 | ``` 64 | ~~~ 65 | 66 | ||| 67 | -------------------------------------------------------------------------------- /configuration/envvars.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: broadcast 3 | order: -100 4 | tags: [config] 5 | --- 6 | # Environment variables 7 | 8 | ## RETYPE_KEY 9 | 10 | A Retype key can be configured as a secret Environment variable and the key is NOT stored in the [wallet](/guides/cli.md#retype-wallet). 11 | 12 | Configuring the `RETYPE_KEY` secret is the prefered technique for configuring a key with a GitHub Pages project that is built and deployed using a [GitHub Action](/guides/github-actions.md). 13 | 14 | The [RETYPE_KEY](../guides/github-actions.md#retype_key) configuration must also be added to your **.github/workflows/retype-action.yml** file. 15 | 16 | You can add a new repository secret to your GitHub repository using the following `/settings/secrets/actions` pattern. Replace the following `` and `` with your repository values: 17 | 18 | ``` 19 | https://github.com///settings/secrets/actions 20 | ``` 21 | 22 | You should now see the **Respository secrets** section with a green button to add a **New repository secret**, similar to the following: 23 | 24 | ![](/static/retype-repository-secrets-list.png) 25 | 26 | Click the **New repository secret** button to add a new secret, which should look similar to the following: 27 | 28 | ![](/static/add-retype-key.png) 29 | 30 | Once the `RETYPE_KEY` secret is added, you should see the following and your Retype project will now build using your key: 31 | 32 | ![](/static/retype-repository-key.png) 33 | 34 | !!! 35 | See [configuring](../guides/github-actions.md/#retype_key) a GitHub Workflow to use your Retype key. 36 | !!! 37 | 38 | ## RETYPE_PASSWORD 39 | 40 | Set an environment variable for the [`protected`](page.md/#protected) and [`private`](page.md/#private) pages. The `RETYPE_PASSWORD` value is set using exactly the same process as the [`RETYPE_KEY`](#retype_key) above. 41 | 42 | If you add both the `RETYPE_PASSWORD` and `RETYPE_KEY`, your list of **Repository secrets** should look like the following: 43 | 44 | ![](/static/retype-repository-secrets-list2.png) 45 | 46 | ## RETYPE_DEFAULT_HOST 47 | 48 | Default [`host`](project.md/#host) to be used by the Retype server instead of `localhost`. 49 | 50 | The `RETYPE_DEFAULT_HOST` secret is set exactly the same as the other secrets. 51 | 52 | ![](/static/add-retype-default-host.png) 53 | -------------------------------------------------------------------------------- /faq.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: question 3 | label: FAQ 4 | order: -1000 5 | --- 6 | # Frequently Asked Questions 7 | 8 | ## Is Retype free to use? 9 | 10 | Yes, Retype is free to use with both open-source and commercial projects up to 100 pages per project. 11 | 12 | With [Retype Pro](/pro/pro.md), you get the following additional features: 13 | 14 | 1. No page limit 15 | 2. The [`Powered by Retype`](/configuration/project.md#poweredbyretype) branding can be removed 16 | 3. [!badge text="NEW" variant="info"] Password protected [`private`](/configuration/page.md#private) and [`protected`](/configuration/page.md#protected) pages 17 | 4. [!badge text="NEW" variant="info"] [Outbound](/configuration/project.md#outbound) link configuration 18 | 5. [!badge text="NEW" variant="info"] [Breadcrumb](/configuration/project.md#breadcrumb) navigation 19 | 5. [!badge text="NEW" variant="info"] [Hub](/configuration/project.md#hub) link 20 | 5. [!badge text="NEW" variant="info"] [Table of Contents](/configuration/project.md#toc) configuration 21 | 22 | ## How do I install Retype? 23 | 24 | Installing Retype is super simple and takes only a few seconds. Please see our [Getting Started](/guides/getting-started.md) guide for detailed installation instructions. 25 | 26 | If you ain't got no time for that, just run the following two commands on a folder that contains at least one **.md** file, depending on your preferred [package manager](/guides/installation.md#step-1-prerequisites). 27 | 28 | +++ npm 29 | ``` 30 | npm install retypeapp --global 31 | retype start 32 | ``` 33 | +++ yarn 34 | ``` 35 | yarn global add retypeapp 36 | retype start 37 | ``` 38 | +++ dotnet 39 | ``` 40 | dotnet tool install retypeapp --global 41 | retype start 42 | ``` 43 | +++ 44 | 45 | ## What is page metadata? 46 | 47 | The page metadata is an optional block of [configuration](/configuration/page.md) that can be placed at the top of any Markdown **.md** page. This block of configuration can also be referred to as the page [Front Matter](https://jekyllrb.com/docs/front-matter/). 48 | 49 | The block of page metadata must be the first item at the top of the **.md** page and must be added between `---` lines above and below the configs. 50 | 51 | ```md sample.md 52 | --- 53 | icon: rocket 54 | --- 55 | # Your page title here 56 | ``` 57 | 58 | The page metadata is completely optional and typically only required when you want to override the Retype defaults. 59 | 60 | You can also add page metadata into a separate **.yml** file, see [page config](/configuration/page.md#separate-yml-file) options. 61 | -------------------------------------------------------------------------------- /hosting/gitlab-pages.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: /static/logos/gitlab.svg 3 | tags: 4 | - guide 5 | - hosting 6 | --- 7 | 8 | # GitLab Pages 9 | 10 | Add a simple CI/CD pipeline to the project to automate the building and deployment of the Retype powered website via [Gitlab Pages](https://docs.gitlab.com/ee/user/project/pages/). 11 | 12 | ## Summary 13 | 14 | - [x] Add a **.gitlab-ci.yml** file to your repository 15 | - [x] [!badge Optional] Add a key to the ENV variables 16 | - [x] Commit a change to the repo to publish the website 17 | 18 | ## .gitlab-ci.yml 19 | 20 | Add the following **.gitlab-ci.yml** file to the project within the root folder. 21 | 22 | ```yaml .gitlab-ci.yml 23 | image: node:latest 24 | 25 | before_script: 26 | - npm install retypeapp --global 27 | 28 | stages: 29 | - deploy 30 | 31 | pages: 32 | stage: deploy 33 | script: 34 | - retype build --key $RETYPE_KEY --output public 35 | artifacts: 36 | paths: 37 | - public/ 38 | only: 39 | - main 40 | 41 | ``` 42 | Gitlab will use the latest available **node** image from the Gitlab Registry and Download & install the latest version of the `retypeapp` via [npm](https://www.npmjs.com/). 43 | 44 | ```yml 45 | image: node:latest 46 | 47 | before_script: 48 | - npm install retypeapp --global 49 | ``` 50 | 51 | GitLab Pages will publish your website every time the deploy stage is triggered by a new commit to the repository. 52 | 53 | The `--key $RETYPE_KEY` is optional. 54 | 55 | The `only: main` argument is to ensure the rebuild is only triggered if commit new code is commited to the main branch. 56 | 57 | ```yml 58 | pages: 59 | stage: deploy 60 | script: 61 | - retype build --key $RETYPE_KEY --output public 62 | artifacts: 63 | paths: 64 | - public/ 65 | only: 66 | - main 67 | ``` 68 | 69 | Commit the **.gitlab-ci.yml** file and push to the repo. 70 | 71 | ## RETYPE_KEY 72 | 73 | If using Retype [Pro](/pro/pro.md), the project requires a Retype key. The key can be configured by adding the [`RETYPE_KEY`](/configuration/envvars.md#retype_key) Environment variable to the repository using the following URL location: 74 | 75 | ``` 76 | # Replace [username] and [project] with your values 77 | https://gitlab.com/[username]/[project]/-/settings/ci_cd 78 | ``` 79 | 80 | The variable type must be `standard`, plus it is recommended to mask and protect the variable. 81 | 82 | After the pipeline finishes successfully, your new generated website will be available online at the following location: 83 | 84 | ``` 85 | # Replace [username] and [project] with your values 86 | https://[username].gitlab.io/[project]/ 87 | ``` -------------------------------------------------------------------------------- /hosting/netlify.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: /static/logos/netlify.svg 3 | tags: 4 | - guide 5 | - hosting 6 | --- 7 | # Netlify 8 | 9 | [Netlify](https://netlify.com) is a popular web hosting platform that allows you to deploy your website easily. In this tutorial, we will go through the steps to sign up, configure, and deploy a Retype built website on Netlify, using GitHub as our version control system. We will assume that the source files for the website are available on the retype branch of the GitHub repository. 10 | 11 | ## Step 1: Add retype-action.yml workflow 12 | 13 | We first recommend adding the [Retype GitHub Build Action](https://retype.com/guides/github-actions/#step-1-add-retype-actionyml-workflow) to your project to automate the building and deployment of your Retype powered website. 14 | 15 | ## Step 2: Sign up for Netlify 16 | 17 | 1. Go to the Netlify website at https://www.netlify.com/. 18 | 1. Click on the "Sign up" button in the top-right corner of the page. 19 | 1. You can sign up using your GitHub account or by providing your email and a password. Choose the method that you prefer. 20 | 1. After signing up, you will be taken to the Netlify dashboard. 21 | 22 | ## Step 3: Create a New Site 23 | 24 | 1. Click on the "New site from Git" button in the Netlify dashboard. 25 | 1. Choose GitHub as the Git provider. 26 | 1. Connect your GitHub account by following the prompts. 27 | 1. Select the repository that you want to deploy. 28 | 1. Choose the branch that you want to deploy (in this case, it is the retype branch). 29 | 1. Netlify will automatically detect the build command and publish directory for your website. If your website uses a different configuration, you can customize 1. these settings in the "Build & Deploy" section. 30 | 1. Click on the "Deploy site" button. 31 | 32 | ## Step 4: Configure Netlify DNS (optional) 33 | 34 | If you want to use a custom domain for your website, you can configure Netlify DNS to point to your domain. 35 | 36 | 1. In the Netlify dashboard, click on the "Domain settings" button. 37 | 1. Under the "Custom domains" section, click on the "Add custom domain" button. 38 | 1. Enter your domain name and click on the "Verify" button. 39 | 1. Follow the prompts to configure your DNS settings. 40 | 1. Once your DNS settings are configured, click on the "Save" button. 41 | 42 | ## Step 5: Deploy Updates 43 | When you make changes to your website, you can deploy them to Netlify using the following steps: 44 | 45 | 1. Push your changes to the retype branch of your GitHub repository. 46 | 1. Netlify will automatically detect the changes and start the deployment process. 47 | 1. Once the deployment is complete, your changes will be live on your website. 48 | -------------------------------------------------------------------------------- /retype.yml: -------------------------------------------------------------------------------- 1 | poweredByRetype: true 2 | 3 | outbound: 4 | exclude: 5 | - retype.com 6 | - github.com 7 | 8 | breadcrumb: 9 | home: ":icon-home:" 10 | 11 | toc: 12 | label: On this page 13 | depth: 2-4 14 | 15 | nav: 16 | mode: stack # Pro key required 17 | icons: 18 | mode: pages # Pro key required 19 | 20 | theme: 21 | base: 22 | # Catppuccin Theme: Latte 23 | #base-color: "#8839ef" 24 | #base-bg: "#eff1f5" 25 | #primary: "#1e66f5" # Blue 26 | #success: "#40a02b" # Green 27 | #danger: "#d20f39" # Red 28 | #warning: "#df8e1d" # Yellow 29 | #royal: "#7287fd" # Lavender 30 | 31 | base-link-weight: 500 32 | nav-item-text-active-weight: 700 33 | image-rounded: 0.75rem 34 | dark: 35 | # Catppuccin Theme: Frappé 36 | #base-color: "#ca9ee6" 37 | #base-bg: "#303446" 38 | #primary: "#8caaee" # Blue 39 | #success: "#a6d189" # Green 40 | #danger: "#e78284" # Red 41 | #warning: "#e5c890" # Yellow 42 | #royal: "#babbf1" # Lavender 43 | 44 | # New Hub link feature, but not used on retype.com 45 | # hub: 46 | # link: https://example.com/ 47 | # alt: Go to example.com 48 | # target: _blank 49 | 50 | # Start in "Pro Mode" trial 51 | start: 52 | pro: true 53 | 54 | # ------------------- 55 | # Retype 56 | # ------------------- 57 | 58 | input: ./ 59 | output: .retype 60 | url: retype.com 61 | 62 | branding: 63 | logo: /static/retype-logo.svg 64 | logoDark: /static/retype-logo-dark.svg 65 | label: v3.12 next 66 | #baseColor: "#3D855E" # Try NEW base color theme setting 67 | 68 | meta: 69 | title: " - Write On! with Retype" 70 | 71 | generator: 72 | paths: root 73 | 74 | edit: 75 | repo: github.com/retypeapp/retype 76 | 77 | links: 78 | - text: Pro Pricing 79 | link: /pro/pro.md 80 | icon: verified 81 | 82 | - text: Blog & News 83 | link: /blog/ 84 | icon: rss 85 | 86 | - text: Support 87 | link: https://github.com/retypeapp/retype/issues 88 | icon: comment-discussion 89 | target: blank 90 | 91 | - text: Social 92 | link: https://twitter.com/retypeapp/ 93 | icon: mention 94 | target: blank 95 | 96 | data: 97 | version: "3.12.0-preview2" 98 | abbreviations: 99 | HTML: Hyper Text Markup Language 100 | CSS: Cascading Style Sheet 101 | 102 | templating: 103 | loopLimit: 2000 104 | 105 | footer: 106 | # Let's demonstrate the power of Retype templating 107 | # by using an include for the footer 108 | copyright: "{{ include \"snippets/footer\" }}" 109 | 110 | links: 111 | - text: About 112 | link: about.md 113 | icon: question 114 | 115 | - text: License 116 | link: license.md 117 | icon: shield-check 118 | -------------------------------------------------------------------------------- /blog/2025-06-06-new-gitHub-pages-community-key.md: -------------------------------------------------------------------------------- 1 | --- 2 | authors: 3 | - name: "@geoffreymcgill" 4 | email: geoff@retype.com 5 | link: https://github.com/retypeapp 6 | tags: 7 | - community 8 | - github 9 | category: 10 | - news 11 | --- 12 | # New GitHub Pages Community Key 13 | 14 | ![](images/2025-06-06.png) 15 | 16 | All projects should have access to professional-grade documentation, no matter their budget. Starting today, the **Retype Pro Community Key** for [GitHub Pages](https://pages.github.com/) brings Retype’s full feature set to any project published on GitHub Pages, **at no cost and with no strings attached**. 17 | 18 | ### Community Key 19 | 20 | ``` 21 | dEVPBhEAT01MR0NBQ0xBT0VHR0NDR0dGT09PRUFDTEZARE9PT09FRERET15aEx0AHAEWWh0bT0Q-pId4N7uwS11nfzalpH2MG9Wql5Jtoc9vFnQMJJeh0WfKhv7CHrYPeg 22 | ``` 23 | 24 | You can add the above [[community]] key to your [Retype Wallet](/guides/cli.md#retype-wallet) using the `retype wallet --add ` command. The command below includes the full `` making it easy to copy/paste: 25 | 26 | ``` 27 | retype wallet --add dEVPBhEAT01MR0NBQ0xBT0VHR0NDR0dGT09PRUFDTEZARE9PT09FRERET15aEx0AHAEWWh0bT0Q-pId4N7uwS11nfzalpH2MG9Wql5Jtoc9vFnQMJJeh0WfKhv7CHrYPeg 28 | ``` 29 | 30 | ## :icon-mark-github: GitHub Pages setup 31 | 32 | With the community key, you can now setup your project to be hosted using **GitHub Pages**. Please review the documentation to configure a [[GitHub Pages]] project with Retype with automatic deployment using [[GitHub Actions]]. 33 | 34 | !!!tip 35 | Do you have any questions? Feel free to contact us using the **:icon-comment: live chat** (see bottom right corner). If we're online, we will be more than happy to answer questions or step you through any setup troublshooting. 36 | !!! 37 | 38 | ## What is included 39 | 40 | - [x] Open-source and Commercial use 41 | - [x] Unlock all projects hosted on `*.github.io` 42 | - [x] Up to 1000 pages 43 | - [x] Free, no cost 44 | - [x] Free Retype Pro upgrades 45 | - [x] Retype Pro features, including [nav](/configuration/project.md#nav), [scheme](/configuration/project.md#scheme), [outbound](/configuration/project.md#outbound), [breadcrumb](/configuration/project.md#breadcrumb), plus all future **Retype Pro** features 46 | 47 | If your project is hosted using GitHub Pages with the default `github.io` domain name, the GitHub Pages community key is available for you. 48 | 49 | ## What is not included 50 | 51 | - [x] [Powered by Retype](/configuration/project.md#poweredbyretype) branding is not removed 52 | 53 | --- 54 | 55 | ## Write On! 56 | 57 | You can now publish polished, full-featured documentation sites with Retype without worrying about cost. 58 | 59 | Let us know what you think on [X](https://x.com/retypeapp) or by opening a GitHub [Issue](https://github.com/retypeapp/retype/issues). Your input helps shape the future of Retype. 60 | -------------------------------------------------------------------------------- /components/comments.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: code-review 3 | tags: [component] 4 | --- 5 | # Comments 6 | 7 | Retype supports adding hidden comments to your Markdown files that are not rendered in the final generated HTML. Comments are useful for adding notes, reminders, or explanations that should only be visible in the source Markdown files. 8 | 9 | ## Basic Syntax 10 | 11 | Comments can be added wrapping `%%` around the comment to be hidden. There are two types of comments: 12 | 13 | 1. Inline comments 14 | 2. Block comments 15 | 16 | ### Inline Comments 17 | 18 | Inline comments can be added anywhere within a line: 19 | 20 | ```md 21 | This is a %%inline %%comment. 22 | 23 | This is an inline comment%at the end of a line%. 24 | 25 | %%This is an %Inline comment at the beginning of a line. 26 | ``` 27 | 28 | The above will be created as: 29 | 30 | ``` 31 | This is a comment. 32 | 33 | This is an inline comment. 34 | 35 | Inline comment at the beginning of a line. 36 | ``` 37 | 38 | ### Block Comments 39 | 40 | Block comments can span multiple lines by using opening `%%` and closing `%%` at the start and end of the comment block. Everything between the opening and closing `%%` will be removed. 41 | 42 | ```md 43 | %% 44 | This is a block comment. 45 | 46 | Block comments can span multiple lines. 47 | %% 48 | ``` 49 | 50 | ## Examples 51 | 52 | ### Adding Notes to Code Blocks 53 | 54 | Comments are particularly useful for adding notes about code blocks that should not be visible in the rendered documentation: 55 | 56 | ~~~md 57 | %% 58 | This code block demonstrates a complex algorithm. 59 | The implementation details are explained in the comments. 60 | %% 61 | ```js 62 | function complexAlgorithm() { 63 | // Implementation details 64 | } 65 | ``` 66 | ~~~ 67 | 68 | ### Documenting Changes 69 | 70 | Comments can be used to document changes or TODOs that should be addressed later: 71 | 72 | ```md 73 | %% 74 | TODO: Update this section when the new API is released. 75 | %% 76 | ``` 77 | 78 | ### Hiding Draft Content 79 | 80 | Comments can be used to hide draft content that isn't ready for publication: 81 | 82 | ```md 83 | %% 84 | Draft content - Not ready for publication 85 | This section needs more examples and better explanations. 86 | %% 87 | ``` 88 | 89 | ## Best Practices 90 | 91 | 1. Use comments to add context that is only relevant to content authors 92 | 2. Keep comments concise and clear 93 | 3. Use block comments for longer explanations 94 | 4. Use inline comments for quick notes or clarifications 95 | 5. Consider using comments to document the reasoning behind certain content decisions 96 | 97 | ## Limitations 98 | 99 | - Comments are completely removed from the final HTML output 100 | - Comments cannot be nested 101 | - Comments should not be used for content that needs to be visible to end users -------------------------------------------------------------------------------- /components/youtube.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: video 3 | tags: [component] 4 | --- 5 | # YouTube 6 | 7 | Retype makes it easy to embed YouTube videos in your documentation. Simply place a YouTube URL on its own line in your markdown file, and Retype will automatically convert it into a responsive embedded video player. 8 | 9 | ## Basic Usage 10 | 11 | To embed a YouTube video, simply paste a YouTube URL on its own line in your markdown document: 12 | 13 | ```markdown 14 | https://www.youtube.com/watch?v=dQw4w9WgXcQ 15 | ``` 16 | 17 | This will be transformed to the following: 18 | 19 | https://www.youtube.com/watch?v=dQw4w9WgXcQ 20 | 21 | ## Supported URL Formats 22 | 23 | Retype supports multiple YouTube URL formats: 24 | 25 | 1. Standard watch URLs: `https://www.youtube.com/watch?v=VIDEO_ID` 26 | 2. Short URLs: `https://youtu.be/VIDEO_ID` 27 | 3. Embed URLs: `https://www.youtube.com/embed/VIDEO_ID` 28 | 29 | All of these formats will be automatically converted to embedded players when placed on their own line. 30 | 31 | ## Player Parameters 32 | 33 | You can customize the embedded YouTube player by adding parameters to the URL. These parameters allow you to control various aspects of the player such as autoplay, loop, controls display, and more. 34 | 35 | Here are some of the most commonly used parameters: 36 | 37 | ### Autoplay 38 | 39 | To automatically start playback when the player loads, add the `autoplay=1` parameter: 40 | 41 | ```markdown 42 | https://www.youtube.com/watch?v=dQw4w9WgXcQ&autoplay=1 43 | ``` 44 | 45 | ### Loop 46 | 47 | To make a video play repeatedly, add the `loop=1` parameter: 48 | 49 | ```markdown 50 | https://www.youtube.com/watch?v=dQw4w9WgXcQ&loop=1 51 | ``` 52 | 53 | ### Controls 54 | 55 | You can hide the player controls by setting `controls=0`: 56 | 57 | ```markdown 58 | https://www.youtube.com/watch?v=dQw4w9WgXcQ&controls=0 59 | ``` 60 | 61 | ### Mute 62 | 63 | To start the video with audio muted (often used in conjunction with autoplay): 64 | 65 | ```markdown 66 | https://www.youtube.com/watch?v=dQw4w9WgXcQ&mute=1&autoplay=1 67 | ``` 68 | 69 | ### Start and End Times 70 | 71 | To specify both start and end times for your video: 72 | 73 | ```markdown 74 | https://www.youtube.com/watch?v=dQw4w9WgXcQ&start=30&end=60 75 | ``` 76 | 77 | This plays only the segment from 30 seconds to 60 seconds. 78 | 79 | For a complete list of all available parameters and their values, refer to the [YouTube Player Parameters](https://developers.google.com/youtube/player_parameters#Parameters) documentation. 80 | 81 | ## Timestamp Support 82 | 83 | You can include a specific start time for your video by adding a timestamp parameter: 84 | 85 | ```markdown 86 | https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=30s 87 | ``` 88 | 89 | This will start the video at the 30-second mark: 90 | 91 | https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=30s 92 | 93 | You can also use the shorter `youtu.be` format with timestamps: 94 | 95 | ```markdown 96 | https://youtu.be/dQw4w9WgXcQ?t=45 97 | ``` 98 | -------------------------------------------------------------------------------- /guides/getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | order: 2000 3 | icon: rocket 4 | tags: [guide] 5 | --- 6 | # Getting Started 7 | 8 | This guide will have you up and running generating your own Retype website in just a few minutes. 9 | 10 | ## What is Retype? 11 | 12 | Retype is a website generator that turns your Markdown `.md` files into a beautiful and functional documentation website. No coding required. Just write in [Markdown](/guides/formatting.md) and Retype handles the rest. 13 | 14 | Retype is perfect for: 15 | - [x] Project documentation 16 | - [x] Knowledge bases 17 | - [x] API docs 18 | - [x] Personal blogs or notes 19 | - [x] Team wikis 20 | - [x] Self-publishing content 21 | 22 | --- 23 | 24 | ## Step 1: Installation 25 | 26 | The first thing to complete is [installing](installation.md) Retype. 27 | 28 | Once you have Retype installed, you can verify using the following command to output the Retype version number: 29 | 30 | ``` 31 | retype --version 32 | ``` 33 | 34 | If the above is not working, then Retype is not installed. 35 | 36 | --- 37 | 38 | ## Step 2: Start Retype 39 | 40 | Still using the command line, navigate to any folder with Markdown files: 41 | 42 | ```bash 43 | cd your-project-folder 44 | ``` 45 | 46 | If you do not have Markdown files in that directory, create a new file such as the following `readme.md`: 47 | 48 | :::code source="../samples/_includes/basic-page.md" ::: 49 | 50 | Then run the command `retype start`: 51 | 52 | ```bash 53 | retype start 54 | ``` 55 | 56 | That's it! Retype will automatically: 57 | 58 | 1. Find your Markdown files 59 | 1. Build your website 60 | 1. Open it in your browser 61 | 1. Watch for changes and reload the browser automatically 62 | 63 | --- 64 | 65 | ## Next Steps: Add more content 66 | 67 | Retype supports standard [Markdown](formatting.md) plus powerful extensions. Experiment with adding the following markdown to your page. 68 | 69 | ### Basic Markdown 70 | 71 | ```md 72 | {{ include "snippets/markdown-sample" }} 73 | ``` 74 | 75 | ### Components and Settings 76 | 77 | Now with a basic introduction to Markdown options, explore the following Retype features: 78 | 79 | [[Components]] 80 | : Rich content blocks like [[table]]s [[callout]]s, [[tab]]s, and [much more](/components/components.md). 81 | 82 | [Project](/configuration/project.md) settings 83 | : Project level configuration for your website 84 | 85 | [Page](https://retype.com/guides/deployment/) settings 86 | : Page level configuration options 87 | 88 | ## Hosting 89 | 90 | To generate the static website files, run the following command: 91 | 92 | ```bash 93 | retype build 94 | ``` 95 | 96 | By default, the files will be copied to a new `.retype` folder within your project, although this is configurable with the [`output`](/configuration/project.md#output) setting. 97 | 98 | The build should only take a few moments to complete. If you have your own web server, you can FTP or copy the files from the `.retype` directory to the web server. 99 | 100 | You can also host your new website using [[GitHub Pages]], [[Cloudflare]], [[GitLab Pages]], [[Docker]], [[Netlify]], or absolutely any other web hosting service. 101 | 102 | {{ include "snippets/support" }} 103 | -------------------------------------------------------------------------------- /components/column.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: columns 3 | tags: [component] 4 | --- 5 | # Column 6 | 7 | The column component is used to create multiple equal width columns with a title for each column. 8 | 9 | The column component is configured by wrapping any block of content in an opening and closing `|||` and setting a title for each column. 10 | 11 | A column can contain any other content, such as text, paragraphs, links, tables, images, and other Retype [components](components.md). 12 | 13 | ```md 14 | ||| Column 1 15 | This is a paragraph inside a **column**. 16 | ||| 17 | ``` 18 | 19 | ||| Column 1 20 | This is a paragraph inside a **column**. 21 | ||| 22 | 23 | !!! 24 | A title is required for each column. The title is separated by one space from the opening `|||`, such as `||| Column 1`. 25 | !!! 26 | 27 | --- 28 | 29 | ## Multiple columns 30 | 31 | One or more columns can be configured by _stacking_ multiple column blocks. 32 | 33 | ```md 34 | ||| Column 1 35 | Content 1 36 | ||| Column 2 37 | Content 2 38 | ||| Column 3 39 | Content 3 40 | ||| 41 | ``` 42 | 43 | ||| Column 1 44 | Content 1 45 | ||| Column 2 46 | Content 2 47 | ||| Column 3 48 | Content 3 49 | ||| 50 | 51 | An unlimited number of columns is possible, although the practical limit will be determined by the width of the page conent area. 52 | 53 | All columns will be the same width and there are no configuration option to make variable width columns. 54 | 55 | --- 56 | 57 | ## Code column 58 | 59 | A special Code Column is created when a code block is configured inside a column and the only content of the column is a code block. The following sample demonstrates a 2-column layout with a code block in the second column position. 60 | 61 | ~~~ 62 | ||| Demo 63 | [!button Button](button.md) 64 | ||| Source 65 | ```md 66 | [!button Button](button.md) 67 | ``` 68 | ||| 69 | ~~~ 70 | 71 | ||| Demo 72 | [!button Button](button.md) 73 | ||| Source 74 | ```md 75 | [!button Button](button.md) 76 | ``` 77 | ||| 78 | 79 | If any other content is directly inside the column, the column and code block will be rendered as normal. For example, let's add some text to the second column and see difference: 80 | 81 | ~~~ 82 | ||| Demo 83 | [!button Button](button.md) 84 | ||| Source 85 | This is a Button component inside a column. 86 | ```md 87 | [!button Button](button.md) 88 | ``` 89 | ||| 90 | ~~~ 91 | 92 | ||| Demo 93 | [!button Button](button.md) 94 | ||| Source 95 | This is a Button component inside a column. 96 | ```md 97 | [!button Button](button.md) 98 | ``` 99 | ||| 100 | 101 | --- 102 | 103 | ## Custom title 104 | 105 | The column titles support configuring with Markdown, so links, [emojis](emoji.md), or [icons](icon.md) could also be added. 106 | 107 | ~~~ 108 | ||| Title with emoji :thumbsup: 109 | 110 | A column title with the [emoji](emoji.md) `:thumbsup:`. 111 | 112 | ||| Title with icon :icon-check-circle: 113 | 114 | A column title with the [icon](icon.md) `:icon-check-circle:`. 115 | 116 | ||| 117 | ~~~ 118 | 119 | ||| Title with emoji :thumbsup: 120 | 121 | A column title with the [emoji](emoji.md) `:thumbsup:`. 122 | 123 | ||| Title with icon :icon-check-circle: 124 | 125 | A column title with the [icon](icon.md) `:icon-check-circle:`. 126 | 127 | ||| 128 | -------------------------------------------------------------------------------- /guides/formatting.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: note 3 | tags: [guide] 4 | label: Markdown (RFM) 5 | --- 6 | # Formatting 7 | 8 | Markdown **.md** pages are plain text documents with a simple human readable syntax that aims to make writing for the internet easier. 9 | 10 | No special software is required to create a **.md** file. Any basic text editor will do. Just save the file with a **.md** file extension. 11 | 12 | Please see [markdownguide.org](https://www.markdownguide.org/cheat-sheet/) for a full demonstration of the formatting possibilities and best practices. 13 | 14 | !!! 15 | View the actual [`formatting.md`](https://github.com/retypeapp/retype/blob/main/guides/formatting.md) source file used to create this page. 16 | !!! 17 | 18 | --- 19 | 20 | ## Quick start 21 | 22 | The following sample demonstrates a very basic `sample.md` page sample with a page title and one paragraph. 23 | 24 | ```md 25 | # Page title here 26 | 27 | This is a paragraph. 28 | ``` 29 | 30 | We can build on the above sample by adding more content and formatting, such as **bold** text, images, and lists. 31 | 32 | ```md 33 | {{ include "snippets/markdown-sample" }} 34 | ``` 35 | 36 | At a very basic level, to create a new page for your Retype project, do the following: 37 | 38 | 1. Make a `readme.md` file 39 | 2. Add a `# title` 40 | 3. Start writing 41 | 42 | ### Home page 43 | 44 | Your project should include a default file (`readme.md`, `index.md`, `default.md`, `welcome.md` or `home.md`) within the root of the project. If there is a default file within the root folder, Retype will use that page as your home page. Clicking on the top-left logo or title will navigate to the home page. 45 | 46 | Outside of the root of your project, adding a file with the exact same name as folder, will also act as a default page for that folder. For instance, adding `/guides/guides.md` is equivalent to `/guides/index.md`. 47 | 48 | The default files can be used inside any folder of the project. Given the following folder and file structure, where `Guides` is a folder... 49 | 50 | ``` 51 | |-- Guides 52 | |-- index.md 53 | |-- getting-started.md 54 | |-- readme.md 55 | ``` 56 | 57 | ...Retype will create three pages in your website and the pages will be available at the following locations: 58 | 59 | 1. `/` 60 | 2. `/guides/` 61 | 3. `/guides/getting-started/` 62 | 63 | !!! 64 | If your home page is the Retype generated **Welcome** page, add a default page to the root of your project. The home page file can be named `readme.md`, `index.md`, `default.md`, `welcome.md` or `home.md`. 65 | !!! 66 | 67 | --- 68 | 69 | ## Components 70 | 71 | In addition to the standard Markdown options, Retype includes many custom [components](/components/components.md) so you can easily add extra [!badge :gem: flair :gem:] to your document. 72 | 73 | The most commonly used Retype components include [Alert](/components/callout.md), [Tab](/components/tab.md), and [Emojis](/components/emoji.md): 74 | 75 | ### Callout 76 | 77 | !!! 78 | This is an Callout 79 | !!! 80 | 81 | ~~~ Sample [Callout](/components/callout.md) component 82 | !!! 83 | This is an Callout 84 | !!! 85 | ~~~ 86 | 87 | ### Tab 88 | 89 | +++ Tab 1 90 | This is Tab 1 91 | +++ Tab 2 92 | This is another Tab 93 | +++ 94 | 95 | ~~~ Sample [Tab](/components/tab.md) component 96 | +++ Tab 1 97 | This is Tab 1 98 | +++ Tab 2 99 | This is another Tab 100 | +++ 101 | ~~~ 102 | 103 | [!ref See all components](/components/components.md) 104 | -------------------------------------------------------------------------------- /configuration/folder.md: -------------------------------------------------------------------------------- 1 | --- 2 | label: Folder 3 | icon: file-directory 4 | tags: [config] 5 | --- 6 | # Folder configuration 7 | 8 | Using the same **.yml** technique and options as [Page configuration](/configuration/page.md), a folder can be configured using a separate **index.yml** file placed inside the folder. 9 | 10 | !!! 11 | Folders support the same properties as [pages](/configuration/page.md), although a few properties that are not applicable in the context of a folder configuration would be ignored, such as [`description`](/configuration/page.md#description). 12 | !!! 13 | 14 | --- 15 | 16 | ## icon 17 | 18 | Set a custom [icon](/configuration/page.md#icon) for the folder. 19 | 20 | ```yml index.yml 21 | icon: gear 22 | ``` 23 | 24 | --- 25 | 26 | ## expanded 27 | 28 | Expand the folder node in the tree navigation with the [expanded](/configuration/page.md#expanded) config. 29 | 30 | ```yml index.yml 31 | expanded: true 32 | ``` 33 | 34 | --- 35 | 36 | ## label 37 | 38 | Change the folder [label](/configuration/page.md#label) used for the left navigation tree node label. 39 | 40 | ```yml index.yml 41 | label: Custom label 42 | ``` 43 | 44 | --- 45 | 46 | ## order 47 | 48 | Move a folder up to the top of the navigation by setting the [order](/configuration/page.md#order). The higher the number, the higher in the stack the folder will be placed. 49 | 50 | ```yml index.yml 51 | order: 1000 52 | ``` 53 | 54 | Move a folder to the bottom of the navigation. The lower the number, the lower in the stack it will be placed. 55 | 56 | ```yml index.yml 57 | order: -1000 58 | ``` 59 | 60 | --- 61 | 62 | ## nextprev 63 | 64 | This config is Retype [!badge PRO](/pro/pro.md) only. 65 | 66 | The `nextprev` configuration controls the display of "Next" and "Previous" navigation buttons at the bottom of each page and whether a page is included in the navigation sequence. 67 | 68 | ### mode 69 | 70 | === mode : `string` 71 | 72 | Controls how the Next/Previous navigation buttons are displayed and whether the page is included in the navigation sequence. 73 | 74 | Option | Description 75 | --- | --- 76 | `show` | Show Next and Previous buttons and include page in sequence (Default) 77 | `hide` | Hide buttons but keep page in sequential order 78 | `exclude` | Hide buttons and exclude page from sequential order 79 | 80 | The default value is `show`. 81 | 82 | ```yml 83 | nextprev: 84 | mode: hide # Pro key required 85 | ``` 86 | 87 | See also [Project](project.md#nextprev-mode) and [Page](page.md#nextprev-mode) configuration of `nextprev.mode`. 88 | === 89 | 90 | --- 91 | 92 | ## permalink 93 | 94 | Configures a new permanent base path for all pages within this directory. 95 | 96 | See **Page** [`permalink`](page.md/#permalink) for full details. 97 | 98 | ```yml index.yml 99 | permalink: /tutorials 100 | ``` 101 | 102 | --- 103 | 104 | ## visibility 105 | 106 | Hide a folder by setting the [visibility](/configuration/page.md#visibility) configuration. 107 | 108 | ```yml index.yml 109 | visibility: hidden 110 | ``` 111 | 112 | Another option to completely ignore a folder or a file would be to prefix the folder name or file name with an underscore `_`. For instance, naming a folder `_guides` would instruct Retype to ignore the folder. 113 | 114 | Password protect an entire folder by setting the `visibility` to either [`protected`](page.md#protected) or [`private`](page.md#private). 115 | 116 | ```yml index.yml 117 | visibility: protected 118 | ``` 119 | -------------------------------------------------------------------------------- /about.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: page 3 | --- 4 | # About 5 | 6 | [Retype](https://retype.com/) is professionally built and supported by a small dedicated team of software engineers. 7 | 8 | Technical support questions, bug reports, and feature requests are best started as an [Issue](https://github.com/retypeapp/retype/issues). 9 | 10 | ## Credits :clap: 11 | 12 | Retype is only made possible because of the hard work of other amazing open-source and commercial projects. 13 | 14 | | Library | License | Role | 15 | | -------------------------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------- | 16 | | [Markdig](https://github.com/xoofx/markdig) | [BSD-2-Clause](https://github.com/xoofx/markdig/blob/master/license.txt) | Markdown parsing | 17 | | [Scriban](https://github.com/scriban/scriban) | [BSD-2-Clause](https://github.com/scriban/scriban/blob/master/license.txt) | Templating, partials, variables | 18 | | [Mojee](https://mojeeio.github.io/Mojee/) | [Mojee](https://mojeeio.github.io/Mojee/license/) | [Emoji](/components/emoji.md) parsing and handling | 19 | | [Octicons](https://primer.github.io/octicons/) | [MIT](https://github.com/primer/octicons/blob/main/LICENSE) | Default bundled [icons](/components/icon.md) | 20 | | [Vue.js](https://vuejs.org/) | [MIT](https://github.com/vuejs/vue/blob/dev/LICENSE) | Client UI framework | 21 | | [Turbo](https://turbo.hotwired.dev/) | [MIT](https://github.com/hotwired/turbo/blob/main/MIT-LICENSE) | HTML over the wire | 22 | | [Lunr](https://lunrjs.com/) | [MIT](https://github.com/olivernn/lunr.js/blob/master/LICENSE) | Search index | 23 | | [Prism](https://prismjs.com/) | [MIT](https://github.com/PrismJS/prism/blob/master/LICENSE) | [Code Block](/components/code-block.md#syntax-highlighting) formatting | 24 | | [Mermaid](https://mermaid-js.github.io/mermaid/) | [MIT](https://github.com/mermaid-js/mermaid/blob/develop/LICENSE) | [Mermaid](/components/mermaid.md) diagrams | 25 | | [KaTeX](https://github.com/KaTeX/KaTeX) | [MIT](https://github.com/KaTeX/KaTeX/blob/master/LICENSE) | [Math formula](/components/math-formulas.md) rendering | 26 | | [Clipboard.js](https://clipboardjs.com) | [MIT](https://clipboardjs.com/) | Code Block copy to clipboard | 27 | | [YamlDotNet](https://github.com/aaubry/YamlDotNet) | [MIT](https://github.com/aaubry/YamlDotNet/blob/master/LICENSE.txt) | YAML parsing | 28 | 29 | ## License 30 | 31 | Please see the Retype [LICENSE](LICENSE.md). 32 | 33 | ## Contact us 34 | 35 | {{ include "snippets/contact-us" }} 36 | -------------------------------------------------------------------------------- /components/embed.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: code-review 3 | tags: [component] 4 | --- 5 | # Embed 6 | 7 | The `embed` component helps with content embedding. 8 | 9 | The embed component syntax is similar to many other Retype components. The `!embed` keyword is used to specify the component and a link to the resource is included. 10 | 11 | ```md 12 | [!embed](link) 13 | ``` 14 | 15 | The link is the full URL to the embedded resource. For instance, embeding a YouTube or Vimeo video would require the following component syntax: 16 | 17 | ```md 18 | [!embed](https://www.youtube.com/embed/C0DPdy98e4c) 19 | ``` 20 | 21 | The above Retype component would render as follows: 22 | 23 | [!embed](https://www.youtube.com/embed/C0DPdy98e4c) 24 | 25 | The following options allow for customization of the embed component. 26 | 27 | --- 28 | 29 | ## AllowFullScreen 30 | 31 | Typically, this attribute is used by embeded videos, such as a YouTube or Vimeo, to enable the **Full screen** button. 32 | 33 | The default value of `allowFullScreen` is `true`. Setting to `false` will remove or disable the full screen button. 34 | 35 | You do not need to explicitly enable the full screen option for videos. By default, the button will be enabled when a Retype `[!embed]` component is used. 36 | 37 | ```md 38 | [!embed](https://www.youtube.com/embed/C0DPdy98e4c) 39 | ``` 40 | 41 | [!embed](https://www.youtube.com/embed/C0DPdy98e4c) 42 | 43 | To explicitly remove or disable the full screen option, include `allowFullScreen="false"` in your `[!embed]` component configuration. 44 | 45 | ```md 46 | [!embed allowFullScreen="false"](https://www.youtube.com/embed/C0DPdy98e4c) 47 | ``` 48 | 49 | [!embed allowFullScreen="false"](https://www.youtube.com/embed/C0DPdy98e4c) 50 | 51 | --- 52 | 53 | ## Aspect 54 | 55 | Specifies the video's pixel aspect ratio. 56 | 57 | ```md 58 | [!embed aspect="4:3"](https://www.youtube.com/embed/C0DPdy98e4c) 59 | ``` 60 | 61 | [!embed aspect="4:3"](https://www.youtube.com/embed/C0DPdy98e4c) 62 | 63 | The setting accepts a number of keyword values according to the list below, each reflecting the embedded area's aspect ratio: 64 | 65 | | Accepted values | 66 | | --- | 67 | | `1:1` | 68 | | `4:3` | 69 | | `16:9` (default) | 70 | | `21:9` | 71 | 72 | --- 73 | 74 | ## El 75 | 76 | Specifies which HTML element should be used to wrap the embedded content. 77 | 78 | ```md 79 | [!embed el="embed"](https://www.youtube.com/embed/C0DPdy98e4c) 80 | ``` 81 | 82 | [!embed el="embed"](https://www.youtube.com/embed/C0DPdy98e4c) 83 | 84 | The setting accepts a number of keyword values according to the list below, each resembling its respective HTML tag in the rendered page: 85 | 86 | | Accepted values | 87 | | --- | 88 | | `embed` | 89 | | `iframe` (default) | 90 | | `video` | 91 | | `object` | 92 | 93 | --- 94 | 95 | ## Height 96 | 97 | Specifies a height for the embedded content's area. 98 | 99 | ```md 100 | [!embed height="120"](https://www.youtube.com/embed/C0DPdy98e4c) 101 | ``` 102 | 103 | [!embed height="120"](https://www.youtube.com/embed/C0DPdy98e4c) 104 | 105 | ## Text 106 | 107 | Adds a caption to the embedded content. 108 | 109 | ```md 110 | [!embed text="Test Video"](https://www.youtube.com/embed/C0DPdy98e4c) 111 | ``` 112 | 113 | [!embed text="Test Video"](https://www.youtube.com/embed/C0DPdy98e4c) 114 | 115 | --- 116 | 117 | ## Width 118 | 119 | Specifies a width for the embedded content's area. 120 | 121 | ```md 122 | [!embed width="300"](https://www.youtube.com/embed/C0DPdy98e4c) 123 | ``` 124 | 125 | [!embed width="300"](https://www.youtube.com/embed/C0DPdy98e4c) 126 | -------------------------------------------------------------------------------- /hosting/github-pages.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: mark-github 3 | tags: 4 | - guide 5 | - hosting 6 | - github 7 | --- 8 | # GitHub Pages 9 | 10 | Hosting your Retype built website on [GitHub Pages](https://pages.github.com/) is free and simple to setup. 11 | 12 | ## Step 1: Add `retype-action.yml` workflow 13 | 14 | We first recommend adding the Retype [Build Action](/guides/github-actions.md) to your project to automate the building and deployment of your Retype powered website. 15 | 16 | !!!tip Community Key 17 | Read about the free [Community](/blog/2025-06-06-new-gitHub-pages-community-key.md) key if hosting on [[GitHub Pages]] and unlock [Pro](/pro/pro.md) features for your project. 18 | !!! 19 | 20 | --- 21 | 22 | ## Step 2: Configure GitHub Pages 23 | 24 | With some simple configuration, GitHub can host your website for free. 25 | 26 | To get started, navigate to the **Settings** > **Pages** page of your repo. The URL should be the following, although you will need to replace `` and `` with your values: 27 | 28 | ``` 29 | https://github.com///settings/pages 30 | ``` 31 | 32 | ### Pick a branch 33 | 34 | By default, the Retype Action will publish your website to a `retype` branch, although you can configure to host from any branch. 35 | 36 | If you have committed the **retype-action.yml** file as detailed in [Step 1](#step-1-add-retype-actionyml-workflow), you should now have a `retype` branch available within the list. Select `retype` then click the **Save** button. 37 | 38 | ![](/static/github-actions-configure-branch.png) 39 | 40 | Your GitHub Pages configuration should now look similar to the following: 41 | 42 | ![](/static/github-actions-enable-pages.png) 43 | 44 | !!! Enforce HTTPS 45 | We recommend that you check the **Enforce HTTPS** checkbox. 46 | !!! 47 | 48 | ### Set a `url` 49 | 50 | With the above sample, GitHub will provide a unique `github.io` subdomain to host your website from. 51 | 52 | Your website will be available from a subfolder of that subdomain. In our scenario, our website will be available in the `/retype/` subfolder. 53 | 54 | For example, the URL will use the following pattern: 55 | 56 | ``` 57 | https://.github.io// 58 | ``` 59 | 60 | You would then set the [`url`](/configuration/project.md#url) configuration with the following, where `` is replaced with your GitHub organization name and `` is replaced with your repository name. 61 | 62 | ```yml 63 | url: .github.io// 64 | ``` 65 | 66 | If your GitHub organization name was `CompanyX` and your repo name was `Docs`, your `url` configuration would be: 67 | 68 | ```yml 69 | url: companyx.github.io/docs/ 70 | ``` 71 | 72 | ## Custom domain 73 | 74 | Instead of using the `github.io` domain, it is possible to configure GitHub Pages to use a custom domain name or subdomain name. 75 | 76 | Just enter your domain name or subdomain name in the **Custom domain** field and click **Save**. 77 | 78 | ![](/static/github-actions-configure-custom-domain.png) 79 | 80 | If your website will be available at `https://example.com`, use `example.com` as the **Custom domain** value. 81 | 82 | If your website will be available at `https://docs.example.com`, use `docs.example.com`. 83 | 84 | You will then need to [configure the DNS](https://docs.github.com/articles/using-a-custom-domain-with-github-pages/) for your domain name. 85 | 86 | The last step would be updating the [`url`](/configuration/project.md#url) project configuration with the same value. For example, if your website will be available at `https://example.com`, use the following `url` configuration: 87 | 88 | ```yml 89 | url: example.com 90 | ``` 91 | -------------------------------------------------------------------------------- /components/reference-link.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: link 3 | tags: [component] 4 | --- 5 | # Reference Link 6 | 7 | A special type of reference link can be configured by using the `!ref` specifier in a link. 8 | 9 | ```md 10 | [!ref](/guides/getting-started.md) 11 | ``` 12 | 13 | [!ref](/guides/getting-started.md) 14 | 15 | By default, the text of the link is not required if the **.md** page you are linking to is within the project. Retype will automatically use the `label` of the **.md** page as the link text. 16 | 17 | --- 18 | 19 | ## Custom text 20 | 21 | The text of the link can be explicitly set by passing as the first part of the component config. In the following sample, we explicitly set the reference link text to `Getting Started`. 22 | 23 | ```md 24 | [!ref Getting Started](/guides/getting-started.md) 25 | ``` 26 | 27 | [!ref Getting Started](/guides/getting-started.md) 28 | 29 | Clicking anywhere within the reference link component will navigate to that new page. 30 | 31 | From a functionality perspective, there is no difference betwen a `!ref` component and a regular hyperlink. The difference between the two is just how they are presented, with a Reference Link component being more prominent than a regular hyperlink. 32 | 33 | --- 34 | 35 | ## Custom icon 36 | 37 | The `icon` used for the reference link component can be customized using a name/value pair syntax for the `text` and `icon` attributes. This allows for setting a custom `icon` and `text` value at the same time. The `icon` attribute can be initialize with one of the following: 38 | - [Octicon](/components/octicons.md) name 39 | - Emoji `:shortcode:` (please see [Mojee](https://mojeeio.github.io/Mojee//emojis) for a full list of supported Emoji shortcodes) 40 | - Image file URL 41 | 42 | The following samples demonstrate setting a custom `icon`: 43 | 44 | ``` 45 | [!ref icon="rocket"](/guides/getting-started.md) 46 | [!ref icon=":rocket:"](/guides/getting-started.md) 47 | [!ref icon="../static/retype-icon.svg"](/guides/getting-started.md) 48 | ``` 49 | 50 | [!ref icon="rocket"](/guides/getting-started.md) 51 | [!ref icon=":rocket:"](/guides/getting-started.md) 52 | [!ref icon="../static/retype-icon.svg"](/guides/getting-started.md) 53 | 54 | By default, the referred page title is used as the component text value and the text can be customized by explicitly passing a separate `text` value. 55 | 56 | ``` 57 | [!ref icon="rocket" text="To the moon"](/guides/getting-started.md) 58 | ``` 59 | 60 | [!ref icon="rocket" text="To the moon"](/guides/getting-started.md) 61 | 62 | --- 63 | 64 | ## Target 65 | 66 | Sets the `target` attribute of the reference link and specifies which window or tab to open the link into. 67 | 68 | [!ref target="blank" text="Retype"](https://retype.com/) 69 | 70 | ```md 71 | [!ref target="blank" text="Retype"](https://retype.com/) 72 | ``` 73 | 74 | If no `target` is configured, the link will open in the current tab. 75 | 76 | 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. 77 | 78 | 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. 79 | 80 | Config `target` value | Runtime `target` value 81 | --- | --- 82 | `blank` | `_blank` 83 | `parent` | `_parent` 84 | `top` | `_top` 85 | `self` | `_self` 86 | `news1` | `news1` 87 | `nEWs2` | `news2` 88 | `recent NEWS` | `recent-news` 89 | 90 | See also the [`links.target`](/configuration/project.md#target) configuration. 91 | -------------------------------------------------------------------------------- /components/table.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: table 3 | tags: [component] 4 | --- 5 | # Table 6 | 7 | Tables are configured using a combination of `|` pipe characters to separate columns and at least three `---` dashes to separate the header row from the table body. 8 | 9 | The following sample demonstrates a basic table configuration: 10 | 11 | ```md 12 | Name | Value 13 | --- | --- 14 | Item 1 | Blue 15 | Item 2 | Green 16 | ``` 17 | 18 | The above configuration creates the following table in the final generated website: 19 | 20 | Name | Value 21 | --- | --- 22 | Item 1 | Blue 23 | Item 2 | Green 24 | 25 | The `|` pipe character column separators are not required to vertically align. Extra whitespace within the column widths is ignored and the result will look the same. 26 | 27 | ```md 28 | Name | Value 29 | --- | --- 30 | Item 1 | Blue 31 | Item 2 | Green 32 | ``` 33 | 34 | --- 35 | 36 | ## Alignment 37 | 38 | The alignment of text within a column can be configured by using the `:` colon character within the header separator row. 39 | 40 | By default, text is left aligned. To center align text, use `:---:` with colons at both ends of the header separator. To right align text, use `---:` with a colon on the right end of the header separator. 41 | 42 | ```md 43 | Name | Value | Description 44 | :--- | :---: | ---: 45 | Item 1 | Blue | This is `Item 1`. 46 | Item 2 | Green | This is `Item 2`. 47 | ``` 48 | 49 | Name | Value | Description 50 | :--- | :---: | ---: 51 | Item 1 | Blue | This is `Item 1`. 52 | Item 2 | Green | This is `Item 2`. 53 | 54 | !!! 55 | Column widths are calculated dynamically by the web browser and will vary depending on the content of the cells. 56 | !!! 57 | 58 | --- 59 | 60 | ## Compact 61 | 62 | A table compact style is possible by applying the `compact` class. 63 | 64 | The compact style reduces the cell padding and text size across the entire table. 65 | 66 | ```md 67 | {.compact} 68 | Name | Value 69 | --- | --- 70 | Item 1 | Blue 71 | Item 2 | Green 72 | ``` 73 | 74 | {.compact} 75 | Name | Value 76 | --- | --- 77 | Item 1 | Blue 78 | Item 2 | Green 79 | 80 | The `compact` class can also be applied to the table using the following technique: 81 | 82 | ```md 83 | Name | Value {.compact} 84 | --- | --- 85 | Item 1 | Blue 86 | Item 2 | Green 87 | ``` 88 | 89 | Name | Value {.compact} 90 | --- | --- 91 | Item 1 | Blue 92 | Item 2 | Green 93 | 94 | ## Nowrap 95 | 96 | The `whitespace-nowrap` class prevents text within table cells from wrapping to the next line, keeping all content on a single line. This is useful for maintaining the layout of content that should stay on one line, such as code snippets or long strings. 97 | 98 | ```md 99 | {.whitespace-nowrap} 100 | Name | Long Message | Description 101 | --- | --- | --- 102 | Item 1 | This is an extra long message that should not wrap in the table | This is a description 103 | Item 2 | Another long content item | Another description 104 | ``` 105 | 106 | {.whitespace-nowrap} 107 | Name | Long Message | Description 108 | --- | --- | --- 109 | Item 1 | This is an extra long message that should not wrap in the table | This is a description 110 | Item 2 | Another long content item | Another description 111 | 112 | You can also apply multiple custom CSS classes to combine formatting options: 113 | 114 | ```md 115 | {.whitespace-nowrap .compact} 116 | Name | Long Message | Description 117 | --- | --- | --- 118 | Item 1 | This is an extra long message that should not wrap in the table | This is a description 119 | Item 2 | Another long content item | Another description 120 | ``` 121 | 122 | {.whitespace-nowrap .compact} 123 | Name | Long Message | Description 124 | --- | --- | --- 125 | Item 1 | This is an extra long message that should not wrap in the table | This is a description 126 | Item 2 | Another long content item | Another description 127 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | --- 2 | label: "Home" 3 | icon: home 4 | backlinks: 5 | enabled: false 6 | --- 7 | # Write On! with Retype 8 | 9 | ![](/static/retype-hero.png) 10 | 11 | [Retype](https://retype.com/) is a static website generator that builds a website based on simple Markdown (.md) text files. Focus on your writing while Retype builds the rest. 12 | 13 | {.callout} 14 | > “I don't want to write code to write docs, I just want to write docs.” 15 | 16 | No coding is required and just one Markdown file, such as a [README.md](https://www.makeareadme.com/), will get you started. 17 | 18 | !!! 19 | The [retype.com](https://retype.com/) website was generated using Retype. View the [source](https://github.com/retypeapp/retype/blob/main/README.md) files used to generate this very page. 20 | !!! 21 | 22 | {.callout} 23 | > “Retype is the perfect fit for my user persona - tech savvy non-devs who want to write using the best web standards out there.” 24 | 25 | A new Retype powered website can be up and running within seconds once Retype is installed, which itself takes only a few seconds. :+1: 26 | 27 | --- 28 | 29 | ## Quick start 30 | 31 | You can install Retype using `npm`, `yarn`, or the `dotnet` CLI. 32 | 33 | From your command line, navigate to a folder location where you have one or more Markdown (.md) files, such as a GitHub project. 34 | 35 | Next, choose one of the following tools to first install `retypeapp` and then start Retype by using the `retype start` [command](/guides/cli.md#retype-start): 36 | 37 | +++ NPM 38 | ``` 39 | npm install retypeapp --global 40 | retype start 41 | ``` 42 | +++ Yarn 43 | ``` 44 | yarn global add retypeapp 45 | retype start 46 | ``` 47 | +++ dotnet 48 | ``` 49 | dotnet tool install retypeapp --global 50 | retype start 51 | ``` 52 | +++ 53 | 54 | That's it! Your new Retype website should be up and running. 55 | 56 | !!! 57 | You will require either [npm](https://www.npmjs.com/get-npm), [Yarn](https://classic.yarnpkg.com/en/docs/install/), or the [dotnet](https://dotnet.microsoft.com/download/dotnet-core) CLI to be installed before installing Retype. Only one of those three is required, although all three could be installed on your machine too. It's up to you. :raised_hands: 58 | 59 | All operating systems are supported: including Mac, Windows, and Linux. 60 | !!! 61 | 62 | --- 63 | 64 | ## Features 65 | 66 | #### :icon-shield-check: It just works 67 | 68 | Retype has been built to be easy to use and should _"just work"_ out-of-the-box without any special configuration or troublesome setup. 69 | 70 | #### :icon-zap: Lightning fast 71 | 72 | Don't blink. Retype was built for speed. 73 | 74 | #### :icon-gear: Easy install 75 | 76 | [Installation](/guides/getting-started.md) takes only a few seconds. Then all you need is one Markdown **.md** file which Retype will start building a new website from. 77 | 78 | #### :icon-plug: Powerful 79 | 80 | Project level [configuration](/configuration/project.md) using **retype.yml** unlocks many more features and customization. 81 | 82 | #### :icon-pencil: Simple formatting 83 | 84 | Pages are [formatted](/guides/formatting.md) using Markdown syntax and Retype [components](/components/components.md). Page level [configuration](/configuration/page.md) is available, such as setting a custom navigation [`label`](/configuration/page.md#label) or [`icon`](/configuration/page.md#icon). 85 | 86 | #### :icon-sync: Live reload 87 | 88 | If a change is detected, such as editing and saving an **.md** file, your Retype website will be updated almost instantly within the browser. 89 | 90 | #### :icon-server: Host anywhere 91 | 92 | Retype generates a basic HTML website that you can host on any web hosting service, or for free using [GitHub Pages](/hosting/github-pages.md), [Netlify](/hosting/netlify.md), or [Cloudflare](/hosting/cloudflare.md). No special server-side software or external dependencies are required. You can host your Retype site as a public website or as a private website within your organization's network. 93 | 94 | --- 95 | 96 | {{ include "snippets/support" }} 97 | -------------------------------------------------------------------------------- /hosting/ftp.md: -------------------------------------------------------------------------------- 1 | --- 2 | label: FTP 3 | icon: upload 4 | tags: [guide, ftp, github] 5 | --- 6 | # Publish using FTP 7 | 8 | Add a simple GitHub Action to your project to automate the building and deployment of your Retype powered website to any FTP host. 9 | 10 | Two Retype GitHub actions will be involved in the process of sync+deploy: 11 | 12 | 1. Retype [Build Action](https://github.com/retypeapp/action-build) 13 | 2. Retype [git-ftp Action](https://github.com/retypeapp/action-git-ftp) 14 | 15 | The first, **Build Action** will automatically build your Retype powered website with each new change that is committed. 16 | 17 | The second, **git-ftp Action** will automatically publish your newly built website to the specified FTP host using the provided credentials. In order to optimally sync only changes between builds, it needs to keep a branch (or a directory within a branch) where it would track differences between sync-up events. By default, the `retype` branch is used, but of course that is also configurable. 18 | 19 | Automatically deploying to FTP requires a basic **retype-action.yml** configuration file to be added to your GitHub repo and some simple project configuration. 20 | 21 | --- 22 | 23 | ## Step 1: Add **retype-action.yml** workflow 24 | 25 | Add the following **retype-action.yml** file to your GitHub project within the `.github/workflows/` folder. 26 | 27 | !!!tip 28 | See the [GitHub Action](/guides/github-actions.md) page for details on setting `RETYPE_KEY`. 29 | !!! 30 | 31 | If the `.github/workflows/` folder does not exist within the root of your project, you can manually create those folders and they will be committed along with the **retype-action.yml**. 32 | 33 | {%{ 34 | ```yaml .github/workflows/retype-action.yml 35 | name: Publish Retype powered website to FTP 36 | on: 37 | workflow_dispatch: 38 | push: 39 | branches: 40 | - main 41 | 42 | jobs: 43 | publish: 44 | name: Publish to FTP host 45 | 46 | runs-on: ubuntu-latest 47 | 48 | steps: 49 | - uses: actions/checkout@v4 50 | 51 | - uses: retypeapp/action-build@latest 52 | 53 | - uses: retypeapp/action-git-ftp@latest 54 | with: 55 | ftp-host: ${{ secrets.FTP_SERVER_ADDRESS }} 56 | ftp-root: public_html 57 | ftp-user: ${{ secrets.FTP_USERNAME }} 58 | ftp-pass: ${{ secrets.FTP_PASSWORD }} 59 | update-branch: true 60 | ``` 61 | }%} 62 | 63 | The above **retype-action.yml** workflow configuration instructs GitHub Actions to automatically build and deploy your website every time commits are pushed to the `main` branch. A copy of the built files is committed into the `retype` branch to maintain change history. 64 | 65 | ### FTP host root 66 | 67 | Usually hosting providers inform a value to fill in the `ftp-root` parameter. Some common values are `public_html`, `wwwroot`, domain name of the website, but it can also be the root of the FTP server itself, where the value of `.` or `/` can be used. 68 | 69 | --- 70 | 71 | ## Step 2: Configure Secrets 72 | 73 | Navigate to the **Settings** > **Secrets** page of your GitHub repository. There, create **New repository secrets** for each of the following parameters: 74 | 75 | - `FTP_SERVER_ADDRESS` with the URL or IP address provided by your hosting. To also pass the FTP port number just use `myhost.address:21`, replacing `21` with the actual port number. 21 is the default and you may omit if so. 76 | - `FTP_USERNAME` will contain the login username to the FTP server 77 | - `FTP_PASSWORD` being probably the most important information to be kept safe in an encrypted secret holds the actual FTP password 78 | 79 | See more about using secrets in actions at [the Encrypted Secrets GitHub Docs article](https://docs.github.com/en/actions/reference/encrypted-secrets). 80 | 81 | --- 82 | 83 | ## Step 3: Commit the workflow 84 | 85 | Now, simply commit and push the `.github/workflows/retype-action.yml` file to GitHub. 86 | 87 | The action will be triggered and GitHub will then perform the following processes: 88 | 89 | - Build the website from markdown files 90 | - Create the branch or commit the changes between builds to GitHub 91 | - Upload the website to the FTP server 92 | 93 | With the first workflow run, it will generate and upload every file. From the second time onwards, only changed files should be updated. 94 | -------------------------------------------------------------------------------- /components/image-alignment-demo.md: -------------------------------------------------------------------------------- 1 | --- 2 | layout: central 3 | visibility: hidden 4 | --- 5 | # Image alignment demo 6 | 7 | Please see [image alignment](image.md#alignment-options) docs for more details. 8 | 9 | ### Center (default) 10 | 11 | ![`center` alignment](/static/sample.jpg) 12 | 13 | Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. 14 | 15 | ### Left 16 | 17 | -![`left` align](/static/sample.jpg) 18 | 19 | Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. 20 | 21 | ### Leftplus 22 | 23 | --![`leftplus` align](/static/sample.jpg) 24 | 25 | Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. 26 | 27 | Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. 28 | 29 | ### Right 30 | 31 | ![`right` align](/static/sample.jpg)- 32 | 33 | Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. 34 | 35 | ### Rightplus 36 | 37 | ![`rightplus` align](/static/sample.jpg)-- 38 | 39 | Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. 40 | 41 | Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. 42 | 43 | ### Centerplus 44 | 45 | --![`centerplus` align](/static/sample-large.jpg)-- 46 | 47 | Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec quam felis, ultricies nec, pellentesque eu, pretium quis, sem. Nulla consequat massa quis enim. Donec pede justo, fringilla vel, aliquet nec, vulputate eget, arcu. In enim justo, rhoncus ut, imperdiet a, venenatis vitae, justo. Nullam dictum felis eu pede mollis pretium. 48 | 49 | Photo by [carlos aranda](https://unsplash.com/@carlosaranda) on [Unsplash](https://unsplash.com/). 50 | -------------------------------------------------------------------------------- /configuration/reserved_words.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: info 3 | tags: [config] 4 | --- 5 | # Reserved words 6 | 7 | There are several folder and file names within a Retype project that incorporate special behaviour and are considered reserved words. 8 | 9 | !!! 10 | All paths to folders or files within Retype are relative to your project [input](/configuration/project.md#input) directory. 11 | !!! 12 | 13 | --- 14 | 15 | ## Folders 16 | 17 | ### /blog 18 | 19 | The `/blog` folder is intended to host a Blog for your website. 20 | 21 | By default, **.md** pages created within the `/blog` folder are assigned the `layout: blog` layout, plus some additional features: 22 | 23 | - A summary page of the blog posts is automatically created at `/blog`. 24 | - An RSS feed of the recent blog posts is created. 25 | - Blog pages get `Newer` and `Older` buttons at the bottom of each page. 26 | - All blog pages are set with the [`layout: blog`](/configuration/page.md#layout) layout, unless otherwise specified in the page metadata. 27 | 28 | !!! 29 | Be sure to review the [`author`](/configuration/page.md#author) and [`date`](/configuration/page.md#date) Page configs if you are writing blog posts. 30 | !!! 31 | 32 | ### /categories 33 | 34 | The default index page of the `/categories` directory is reserved for a summary of any [category](/configuration/page.md#category) configs. Every category configured within an **.md** page of your Retype project will have a corresponding entry here. 35 | 36 | Similar to [`/tags`](#tags), you can also add content to the `/categories` page by creating your own `/categories/index.md` page. Retype will create your page as normal and then add the list of Categories below your custom content. 37 | 38 | ### /resources 39 | 40 | Any files placed within this directory will be copied to the [output](/configuration/project.md#output) directory. Please see the [`include`](/configuration/project.md#include) and [`exclude`](/configuration/project.md#exclude) configs for fine-grained control over including or excluding files or folders. 41 | 42 | ### /tags 43 | 44 | The `/tags` directory is reserved for [tags](/configuration/page.md#tags). Every tag name configured within an **.md** page will have a corresponding entry here. 45 | 46 | Similar to [`/categories`](#categories), you can also add content to the `/tags` page by creating your own `/tags/index.md` page. Retype will create your page as normal and then add the list of Tags below your custom content. 47 | 48 | --- 49 | 50 | ## Files 51 | 52 | ### CNAME 53 | 54 | A **CNAME** file will be automatically created if the [`url`](/configuration/project.md#url) is configured with a domain name or subdomain. 55 | 56 | For instance, including `url: docs.example.com` within your **retype.yml** project config file also instructs Retype to create a **CNAME** file with the value `docs.example.com`. That **CNAME** file is used by [GitHub Pages](/guides/github-actions.md) and possibly other website hosting services as the way to configure custom domain name hosting. 57 | 58 | If you manually create a **CNAME** file within the root of the [input](/configuration/project.md#input) folder of your project, Retype will not automatically create the **CNAME** file, even if the [`url`](/configuration/project.md#url) or [`cname`](/configuration/project.md#cname) is configured or conflicts. 59 | 60 | ### Default pages 61 | 62 | {{ include "snippets/default-pages.md" }} 63 | 64 | ### Project config 65 | 66 | By default, if you do not pass an explicit project configuration file name in the [``](/guides/cli.md#retype-start) command line argument, Retype will search for your project config using the following case insensitive priority: 67 | 68 | 1. `retype.yml` 69 | 2. `retype.yaml` 70 | 3. `retype.json` 71 | 72 | For instance, if you run the [CLI](/guides/cli.md) command `retype start docs`, Retype will first try to find the project configuration file **docs/retype.yml**. If not found, then **docs/retype.yaml** will be tested and so on. 73 | 74 | If you run the command `retype start docs/retype.json`, even if a **retype.yml** is present, Retype will only read the **retype.json** file as you are explicitly passing the project configuration file path. 75 | 76 | !!! 77 | Custom project config file names are also possible by explicitly passing a file name, such as `retype start docs.yml`. Where **docs.yml** is used instead of **retype.yml**, even if **retype.yml** is present. 78 | !!! 79 | 80 | Once a project configuration file is found, it is used. If the other files are found, they are ignored. Retype will not merge or override different configs or conflicting configs between two or more project files. 81 | -------------------------------------------------------------------------------- /hosting/heroku.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: 3 | tags: 4 | - guide 5 | - hosting 6 | visibility: hidden 7 | --- 8 | # Heroku 9 | 10 | Easily publish your project using [Heroku](https://heroku.com/) using the the dedicated [buildpack](https://github.com/retypeapp/heroku-buildpack/) and let Retype do the building for you! 11 | 12 | ![](heroku-logo.png) 13 | 14 | ## Step 1: Clone repository 15 | 16 | Clone a git repository using the `git` command line client. 17 | 18 | For demonstrations purposes, let's use the Retype website [repo](https://github.com/retypeapp/retype), but of course you likely want to use your own project. 19 | 20 | ```bash 21 | git clone https://github.com/retypeapp/retype 22 | ``` 23 | 24 | Cloning will create a `retype` directory containing a copy of this website. 25 | 26 | ### Switch folders 27 | 28 | This is important for Heroku to be able to set up the repository remotes in the next step. 29 | 30 | ```bash 31 | cd retype 32 | ``` 33 | 34 | --- 35 | 36 | ## Step 2: Create the app 37 | 38 | Run the following command to create a new Heroku app instance. 39 | 40 | ```bash 41 | heroku create my-app-name 42 | ``` 43 | 44 | !!! 45 | Remember to replace `my-app-name` with the app name of your preference. The name of the app is prefixed to the public app address. 46 | 47 | With the sample above, that would be `https://my-app-name.herokuapp.com/`. 48 | !!! 49 | 50 | ### Login to Heroku 51 | 52 | If you are not already signed into Heroku, run the `heroku login` command. 53 | 54 | ```bash 55 | heroku login 56 | ``` 57 | 58 | --- 59 | 60 | ## Step 3: Enable buildpack 61 | 62 | 66 | 67 | Enable the Retype Heroku buildpack using the Heroku CLI. 68 | 69 | ```bash 70 | heroku buildpacks:set https://github.com/retypeapp/heroku-buildpack 71 | ``` 72 | 73 | The Retype Heroku buildpack will do all the magic. Once the documentation project is pushed to Heroku, the Retype buildpack will start up and handle the documentation build. 74 | 75 | --- 76 | 77 | ## Step 4: Publish 78 | 79 | Push the repository to Heroku using the `git push` command. 80 | 81 | ```bash 82 | git push heroku main 83 | ``` 84 | 85 | The `git push` process should only take a few seconds to finish. Once complete, the last lines of output should print out the URL to your app. 86 | 87 | With the app name used in this guide, that URL would be `https://my-app-name.herokuapp.com/`. 88 | 89 | !!! 90 | Building your documentation project locally is not required, other than for testing. You do not need to commit any built files. The Heroku buildpack will handle all that for you! The project is built remotely. 91 | !!! 92 | 93 | --- 94 | 95 | ## Publishing your project 96 | 97 | Any Retype project can be deployed to Heroku. Just use your repo in [Step 1](#step-1-clone-repository). 98 | 99 | The buildpack only requires a **retype.yml** file to build the documentation and the file can be provided serveral different ways: 100 | 101 | 1. A **retype.yml** file in the root of your project, or 102 | 2. A **retype.yml** file anywhere in the repository, or 103 | 3. The full path to a directory containing **retype.yml** or directly to the file itself. Configure using the Heroku [config var](https://devcenter.heroku.com/articles/config-vars) `RETYPE_CONFIG`, or 104 | 105 | Please review the [Project](/configuration/project.md) configuration docs for all possible **retype.yml** options. 106 | 107 | --- 108 | 109 | ## Further Reading 110 | 111 | - [x] Install Retype to run locally, see [Getting Started](/guides/getting-started.md) 112 | - [x] Troubleshoot Heroku push/build issues, see [troubleshooting](https://github.com/retypeapp/heroku-buildpack/#troubleshooting) 113 | - [x] Check out the open-source Retype Heroku [buildpack](https://github.com/retypeapp/heroku-buildpack/) 114 | - [x] To create a Heroku account, see [heroku.com](https://heroku.com) 115 | - [x] Download the Heroku [CLI](https://devcenter.heroku.com/articles/heroku-cli) 116 | - [x] Heroku CLI [documentation](https://devcenter.heroku.com/categories/command-line) -------------------------------------------------------------------------------- /components/code-snippet.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: code 3 | tags: [component] 4 | --- 5 | # Code Snippet 6 | 7 | A code snippet allow you to include the content of another text file or a portion of that file into a code block on another page. 8 | 9 | A common scenario for using the code snippet component is to include a portion of a source code file located elsewhere within your repository, but not explicitly within the documentation. For instance, you could include code samples directly from the source code of the project you are documenting, or import code being used within a working demo. 10 | 11 | The syntax for a code snippet component is: 12 | 13 | ``` 14 | :::code source="" ::: 15 | ``` 16 | 17 | In the following sample, we reference a local `../static/sample.js` file and get the first two lines of the file. 18 | 19 | +++ Demo 20 | :::code source="../static/sample.js" range="1-2" ::: 21 | +++ Source 22 | ``` 23 | :::code source="../static/sample.js" range="1-2" ::: 24 | ``` 25 | +++ 26 | 27 | --- 28 | 29 | ## Source 30 | 31 | The `source` is the local path to a file. 32 | 33 | ``` 34 | :::code source="" ::: 35 | ``` 36 | 37 | Typically, the `source` file must be located within the same repository. At least the file needs to be accessible whenever the project is built by Retype. If building locally, the `source` can be located anywhere accessible in the local file system, although if you are using the Retype [GitHub Action](/guides/github-actions.md), the file must be within the same repo or accessible by the Action. 38 | 39 | In the following demo, we link to the `sample.js` file and include the entire contents of that file into the code block: 40 | 41 | +++ Demo 42 | :::code source="../static/sample.js" ::: 43 | +++ Source 44 | ``` 45 | :::code source="../static/sample.js" ::: 46 | ``` 47 | +++ 48 | 49 | --- 50 | 51 | ## Range 52 | 53 | A `range` of lines to include from the `source` file can configured, instead of including the entire contents of the file. If no `range` is configured, the entire contents of the file will be included. 54 | 55 | ``` 56 | :::code source="" range="" ::: 57 | ``` 58 | 59 | The `range` accepts a comma separated list of individual line numbers or a dash separated range, such as `2-24` to include only lines #2 to #24 of the file. 60 | 61 | ``` 62 | range="2" // A single line 63 | range="2-24" // A range of lines 64 | range="2,12-24,26" // A combination of ranges 65 | ``` 66 | 67 | In the following demo, we link to the `sample.js` file and include the first two lines of that file into the code block. 68 | 69 | +++ Demo 70 | :::code source="../static/sample.js" range="1-2" ::: 71 | +++ Source 72 | ``` 73 | :::code source="../static/sample.js" range="1-2" ::: 74 | ``` 75 | +++ 76 | 77 | If the copied code block from the `range` is indented, the left indentation will be removed from the file output so that the code block is normalized with a left-aligned positioning. 78 | 79 | --- 80 | 81 | ## Title 82 | 83 | An optional `title` can be specified. 84 | 85 | ``` 86 | :::code language="" title="" ::: 87 | ``` 88 | 89 | Let's add a `title` to our `../static/sample.js` code snippet. Within the **.md** file, the configuration would look like... 90 | 91 | +++ Demo 92 | :::code source="../static/sample.js" range="1-2" title="../static/sample.js" ::: 93 | +++ Source 94 | ``` 95 | :::code source="../static/sample.js" range="1-2" title="../static/sample.js" ::: 96 | ``` 97 | +++ 98 | 99 | --- 100 | 101 | ## Language 102 | 103 | The final code blocks allow for a language type to be configured which enables code syntax highlighting within the code block. 104 | 105 | The `language` property can be set with any reference language value supported by the Markdown [code blocks](code-block.md) in Retype. 106 | 107 | ``` 108 | :::code source="<path-to-file>" language="<language>" ::: 109 | ``` 110 | 111 | By default, Retype will try to intelligently determine the `language` based on the file extension of the `source` and the automatically set the `language` property. For instance, if the `source` file is a JavaScript **.js** file, Retype will set the `language` of the code snippet to `js`. 112 | 113 | If the `language` property is explicitly set, Retype will use that value. If the `language` cannot be determined by Retype, no language reference is set and the code block is rendered without syntax highlighting. 114 | 115 | --- 116 | 117 | ## Region 118 | 119 | For C# files with a `.cs` file extension, an optional `region` name can be configured instead of a [`range`](#range) which will make a copy of all lines between the named `#region` and `#endregion` directives. The lines containing the `#region` and `#endregion` directives should not be included in the new code block. 120 | 121 | ``` 122 | :::code source="<path-to-file>" region="<region-name>" ::: 123 | ``` 124 | 125 | If the copied code block from the `region` is indented, the left indentation will be removed from the file output so that the code block is normalized with a left-aligned positioning. -------------------------------------------------------------------------------- /blog/2025-06-09-whats-new-in-retype-v310.md: -------------------------------------------------------------------------------- 1 | --- 2 | authors: 3 | - name: "@geoffreymcgill" 4 | email: geoff@retype.com 5 | link: https://github.com/retypeapp 6 | category: 7 | - release 8 | --- 9 | # What's New in Retype v3.10 10 | 11 | ![](images/2025-06-09.png) 12 | 13 | We're excited to share the latest release of [Retype](https://retype.com/), packed with features that make documentation more flexible and powerful. This release focuses on improving content authoring, navigation control, and extending markdown capabilities. 14 | 15 | See the full [[CHANGELOG#v3100|changelog]] for the `v3.10` release. 16 | 17 | ## Next/Previous Navigation Control 18 | 19 | ![Previous and Next page sequencing navigation](images/2025-06-09-nextprev.png) 20 | 21 | Take control of your documentation's navigation flow with the new `nextprev` configuration. This feature lets you customize the visibility and sequencing of the Next/Previous navigation at the bottom of each page and can be configured at the `project`, `page`, and `folder` levels. 22 | 23 | !!! 24 | This feature is a [!badge Pro|info] only feature and a Retype [key](/pro/pro.md) is required to enable. 25 | !!! 26 | 27 | ### Modes 28 | 29 | Option | Description 30 | --- | --- 31 | `show` | Show Next and Previous buttons and include page in sequence (Default) 32 | `hide` | Hide buttons but keep page in sequential order 33 | `exclude` | Hide buttons and exclude page from sequential order 34 | 35 | ### Project-Level 36 | 37 | Configure project wide by adding the setting to your `retype.yml` file. See [docs](/configuration/project.md#nextprev). 38 | 39 | ```yaml 40 | nextprev: 41 | mode: show 42 | ``` 43 | 44 | ### Page-Level 45 | 46 | Configure on individual pages. See [docs](/configuration/page.md#nextprev). 47 | 48 | ```yaml 49 | --- 50 | nextprev: 51 | mode: exclude 52 | --- 53 | ``` 54 | 55 | !!!tip 56 | Configuring with `exclude` is especially useful for landing pages or standalone content pages that shouldn't be part of your main documentation flow. 57 | !!! 58 | 59 | ### Folder-Level 60 | 61 | Configure an entire folder by adding the setting to a `index.yml` file within the folder, or any of the default folder pages, such as `readme.md`, `index.md`, or `default.md`. See [docs](/configuration/folder.md#nextprev). 62 | 63 | ```yaml 64 | nextprev: 65 | mode: hide 66 | ``` 67 | 68 | ## Hidden Comments 69 | 70 | You can now add hidden [[comments]] to your markdown that won't appear in the final website, making it easier to leave notes for yourself or your team. See [docs](/components/comments.md). 71 | 72 | ### Inline Comments 73 | 74 | Add comments anywhere in your text using the `%%comment%%` syntax: 75 | 76 | ```markdown 77 | The comment disappears completely%%from the rendered page%%. 78 | ``` 79 | 80 | The comment disappears completely%%from the rendered page%%. 81 | 82 | ### Block Comments 83 | 84 | For longer notes or multi-line comments, use the comment block syntax: 85 | 86 | ```markdown 87 | %% 88 | This entire block is a comment. 89 | You can write multiple lines here. 90 | None of this will appear in the final output. 91 | %% 92 | ``` 93 | 94 | This is particularly useful for: 95 | - Leaving editing notes for team members 96 | - Temporarily hiding content without deleting it 97 | - Adding context that shouldn't be public 98 | 99 | ## New `tip` Callout Variant 100 | 101 | A new [[callout]] type has been added specifically for helpful tips, complete with a lightbulb icon. 102 | 103 | ```markdown 104 | !!!tip Pro Tip 105 | Here's a helpful suggestion that will save you time. 106 | !!! 107 | ``` 108 | 109 | !!!tip Pro Tip 110 | Here's a helpful suggestion that will save you time. 111 | !!! 112 | 113 | The tip callout uses a friendly green color scheme and stands out nicely from other callout types like warnings or notes. It's perfect for sharing best practices or helpful hints. 114 | 115 | ## Generic Attributes for List Items 116 | 117 | You can now apply CSS classes, IDs, and other custom attributes directly to individual [list items](/components/list.md#generic-attributes) using the generic attribute syntax. See [docs](/components/list.md#generic-attributes). 118 | 119 | ```markdown 120 | - Regular list item 121 | - Important item {.highlight} 122 | - Item with ID {#special-item} 123 | - Item with multiple attributes {#my-id .class-name data-value="test"} 124 | ``` 125 | 126 | The above Markdown sample creates the following HTML with the added attributes: 127 | 128 | ```html 129 | <ul> 130 | <li>Regular list item</li> 131 | <li class="highlight">Important item</li> 132 | <li id="special-item">Item with ID</li> 133 | <li id="my-id" class="class-name" data-value="test">Item with multiple attributes</li> 134 | </ul> 135 | ``` 136 | 137 | --- 138 | 139 | ## Write On! 140 | 141 | This release represents significant improvements to content authoring and navigation control. We're continuing to refine these features based on your feedback. 142 | 143 | Try out `v3.10` and experiment with the new features, then let us know what you think on [X](https://x.com/retypeapp) or by opening a GitHub [Issue](https://github.com/retypeapp/retype/issues). Your input helps shape the future of Retype. 144 | 145 | -------------------------------------------------------------------------------- /components/panel.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: rows 3 | tags: [component] 4 | --- 5 | # Panel 6 | 7 | A Panel is created by surrounding a block of content with `===` and including a `title` for the Panel. 8 | 9 | ``` 10 | === My Panel 11 | This is a Panel. Expanded by default. 12 | === 13 | ``` 14 | 15 | === My Panel 16 | This is a Panel. Expanded by default. 17 | === 18 | 19 | The `title` must be separated from the opening `===` by one space. The pattern `=== My Panel` will work as expected, and `===My Panel` will not. 20 | 21 | Multiple Panels can be [stacked](#stacking) by repeating Panel component configurations. 22 | 23 | ``` 24 | === Panel 1 25 | Content 1 26 | === Panel 2 27 | Content 2 28 | === 29 | ``` 30 | 31 | === Panel 1 32 | 33 | Content 1 34 | 35 | === Panel 2 36 | 37 | Content 2 38 | 39 | === 40 | 41 | !!! 42 | Currently, Panel components cannot be nested within each other, only stacked. We're hoping to support nesting Panels in a future release. [Let us know](https://github.com/retypeapp/retype/issues) if you require the functionality. 43 | 44 | All other components can be nested within any Panel component. 45 | !!! 46 | 47 | --- 48 | 49 | ## Collapsed 50 | 51 | By default, Panels are collapsible and will initially render in their expanded state. You can configure Panels to initially render in their collapsed state by using `==-` specifier. 52 | 53 | ``` 54 | ==- My Panel 55 | This is a collapsed Panel. :+1: 56 | === 57 | ``` 58 | 59 | ==- My Panel 60 | 61 | This is a collapsed Panel. :+1: 62 | 63 | === 64 | 65 | Either just the opening `==-` can be configured, or both opening and closing `==-` can be used. 66 | 67 | ``` 68 | ==- My Panel 69 | This is another collapsed Panel. 70 | ==- 71 | ``` 72 | 73 | ==- My Panel 74 | 75 | This is another collapsed Panel. 76 | 77 | ==- 78 | 79 | --- 80 | 81 | ## Inner content 82 | 83 | Any content can be added inside a Panel, include other components such as a [code block](code-block.md) and tables. 84 | 85 | ~~~ 86 | === Code Sample 87 | ```js 88 | const msg = "Hello, world"; 89 | 90 | console.log(msg); 91 | ``` 92 | 93 | Name | Type | Value | Description 94 | --- | --- | --- | --- 95 | prop1 | type1 | value1 | A `type1` property 96 | prop2 | type2 | value2 | A `type2` property 97 | === 98 | ~~~ 99 | 100 | === Code Sample 101 | 102 | ```js 103 | const msg = "Hello, world"; 104 | 105 | console.log(msg); 106 | ``` 107 | 108 | Name | Type | Value | Description 109 | --- | --- | --- | --- 110 | prop1 | type1 | value1 | A `type1` property 111 | prop2 | type2 | value2 | A `type2` property 112 | 113 | === 114 | 115 | --- 116 | 117 | ## Stacking 118 | 119 | Multiple Panel components can be _stacked_ into a group by repeating Panel component configurations. 120 | 121 | A basic scenario is grouping two Panels: 122 | 123 | ``` 124 | === Panel 1 125 | Content for the **first** panel. 126 | === Panel 2 127 | Content for the **second** panel. 128 | === 129 | ``` 130 | 131 | === Panel 1 132 | 133 | Content for the **first** panel. 134 | 135 | === Panel 2 136 | 137 | Content for the **second** panel. 138 | 139 | === 140 | 141 | As well, individual Panels within a stack can be configured as collapsed. 142 | 143 | The following sample demonstrates a two-panel stack with the second Panel being collapsed. 144 | 145 | ``` 146 | === Expanded Panel 147 | 148 | Panels are expanded by default, but can be configured as collapsed too! 149 | 150 | ==- Collapsed Panel 151 | 152 | Add any content or components inside a Panel. 153 | 154 | === 155 | ``` 156 | 157 | === Expanded Panel 158 | 159 | Panels are expanded by default, but can be configured as collapsed too! 160 | 161 | ==- Collapsed Panel 162 | 163 | :partying_face: You found me! 164 | 165 | === 166 | 167 | --- 168 | 169 | ## Accordion 170 | 171 | Panels can be used to create an accordion-style layout, perfect for FAQs or collapsible content sections. Here's an example with three collapsed panels: 172 | 173 | ``` 174 | ==- What is Retype? 175 | Retype is a modern documentation generator that helps you create beautiful documentation websites from your Markdown files. It's designed to be fast, flexible, and easy to use. 176 | 177 | ==- How do I get started? 178 | Getting started with Retype is simple! Just install the Retype CLI and run `retype init` in your project directory. Then add your Markdown files and run `retype start` to preview your documentation locally. 179 | 180 | ==- Where can I deploy my Retype site? 181 | Retype sites can be deployed to any static hosting service like GitHub [Pages](/hosting/github-pages.md), [Netlify](/hosting/netlify.md), Vercel, or your own web server. 182 | === 183 | ``` 184 | 185 | ==- What is Retype? 186 | Retype is a modern documentation generator that helps you create beautiful documentation websites from your Markdown files. It's designed to be fast, flexible, and easy to use. 187 | 188 | ==- How do I get started? 189 | Getting started with Retype is simple! Just install the Retype CLI and run `retype init` in your project directory. Then add your Markdown files and run `retype start` to preview your documentation locally. 190 | 191 | ==- Where can I deploy my Retype site? 192 | Retype sites can be deployed to any static hosting service like GitHub [Pages](/hosting/github-pages.md), [Netlify](/hosting/netlify.md), Vercel, or your own web server. 193 | === 194 | 195 | -------------------------------------------------------------------------------- /components/container.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: container 3 | tags: [component] 4 | --- 5 | # Container 6 | 7 | A Container component can be used to wrap any content in a `<div>` container. 8 | 9 | A Container component is created by adding `:::` above and below any content. 10 | 11 | In of itself, there should be no visible difference between content inside a Container vs not inside a Container. Visually, the final rendered content should look the same. For example: 12 | 13 | ::: 14 | This text is inside a Container component. 15 | ::: 16 | 17 | The syntax used to create the above line is as follows: 18 | 19 | ```md 20 | ::: 21 | This text is inside a Container component. 22 | ::: 23 | ``` 24 | 25 | The difference is in the generated HTML. The above line of text is now created within a new `<div>` element: 26 | 27 | ```html 28 | <div> 29 | <p>This text is inside a Container component.</p> 30 | </div> 31 | ``` 32 | 33 | --- 34 | 35 | ## Custom CSS class 36 | 37 | The power of the Container component is how custom styling can be applied to the `<div>` container. 38 | 39 | <style> 40 | .sample { 41 | text-align: center; 42 | color: #1956AF; 43 | border-radius: 10px; 44 | background-color: #E1EDFF; 45 | border: 1px solid #1956AF; 46 | padding: 20px 20px 0 20px; 47 | margin-bottom: 20px; 48 | } 49 | </style> 50 | :::sample 51 | This text is wrapped in a Container component and has a custom css `class` applied. 52 | ::: 53 | 54 | The above Container is configured by assigning the `:::sample` class to the opening of Container, and then defining an inline CSS class. 55 | 56 | ```md 57 | <style> 58 | .sample { 59 | text-align: center; 60 | color: #1956AF; 61 | border-radius: 10px; 62 | background-color: #E1EDFF; 63 | border: 1px solid #1956AF; 64 | padding: 20px 20px 0 20px; 65 | margin-bottom: 20px; 66 | } 67 | </style> 68 | :::sample 69 | This text is wrapped in a Container component and has a custom css `class` applied. 70 | ::: 71 | ``` 72 | 73 | --- 74 | 75 | ## Generic attributes 76 | 77 | The Container component also supports applying generic attributes. 78 | 79 | :::sample { #container1 } 80 | This Container has a custom `id` attribute. 81 | ::: 82 | 83 | The following sample is used to configure the above Container: 84 | 85 | ```md 86 | :::sample { #container1 } 87 | This Container has a custom `id` attribute. 88 | ::: 89 | ``` 90 | 91 | The generated HTML would be: 92 | 93 | ```html 94 | <div id="container1" class="sample"> 95 | <p>This Container has a custom <code>id</code> attribute.</p> 96 | </div> 97 | ``` 98 | 99 | --- 100 | 101 | ## Custom global css 102 | 103 | It is also possible to include a global styles by adding to a new **/_includes/head.html** file. 104 | 105 | The contents of **_includes/head.html** are added to all pages of the generated website. 106 | 107 | For example, the inline `<style>` block above could be moved out of the page and then included automatically into all pages. 108 | 109 | Create a new **head.html** file and place the file within a **/_includes/** folder in the root of your project. 110 | 111 | ```css _includes/head.html 112 | <style> 113 | .sample { 114 | text-align: center; 115 | color: #1956AF; 116 | border-radius: 10px; 117 | background-color: #E1EDFF; 118 | border: 1px solid #1956AF; 119 | padding: 20px 20px 0 20px; 120 | margin-bottom: 20px; 121 | } 122 | </style> 123 | ``` 124 | 125 | Moving the `<style>` block into the **_includes/head.html** is all you need to do. Save the file and your new `.sample` css class is now available on all pages your website. 126 | 127 | :::sample 128 | This Container uses the `sample` class. 129 | ::: 130 | 131 | ``` 132 | :::sample 133 | This Container uses the `sample` class. 134 | ::: 135 | ``` 136 | 137 | ### Global .css file 138 | 139 | Since the **_includes/head.html** can contain any custom HTML, you could also move your CSS into a separate **.css** file that is included on all pages of your generated website. 140 | 141 | ```html /_includes/head.html 142 | <link href="/static/custom.css" rel="stylesheet" /> 143 | ``` 144 | 145 | ```css /static/custom.css 146 | .sample { 147 | text-align: center; 148 | color: #1956AF; 149 | border-radius: 10px; 150 | background-color: #E1EDFF; 151 | border: 1px solid #1956AF; 152 | padding: 20px 20px 0 20px; 153 | margin-bottom: 20px; 154 | } 155 | ``` 156 | 157 | Being a separate **.css** file, web browsers will automatically cache the file, so re-downloading of the file with each page request is not required. This will improve the performance of your website. 158 | 159 | !!!danger 160 | Retype does not validate any of the custom HTML added to the **_includes/head.html**. It is up to you to ensure this HTML is correct and does not interfere or break anything within the website. 161 | !!! 162 | 163 | ## Samples 164 | 165 | ### Center on Page 166 | 167 | Text, a [Button](button.md), or any similar Retype component, can be center aligned on the page by nesting the component inside a Container and applying the `content-center` or `text-center` css class. 168 | 169 | The following samples demonstrate center alignment of a Button and Text: 170 | 171 | :::content-center 172 | [!button My Button] 173 | ::: 174 | 175 | :::text-center 176 | This text should be centered :+1: 177 | ::: 178 | 179 | ``` 180 | :::content-center 181 | [!button My Button] 182 | ::: 183 | 184 | :::text-center 185 | This text should be centered :+1: 186 | ::: 187 | ``` -------------------------------------------------------------------------------- /blog/2025-05-28-whats-new-in-retype-v39.md: -------------------------------------------------------------------------------- 1 | --- 2 | authors: 3 | - name: "@geoffreymcgill" 4 | email: geoff@retype.com 5 | link: https://github.com/retypeapp 6 | category: 7 | - release 8 | --- 9 | # What's New in Retype v3.9 10 | 11 | ![](images/2025-05-28.png) 12 | 13 | Retype v3.9 brings improvements to [[callout]] components, broader syntax features to support other systems, enhanced image handling, and better print functionality. This release focuses on making Retype more compatible with other documentation platforms while adding powerful new features. 14 | 15 | ## New `question` Callout 16 | 17 | Meet the new `question` [[callout]] variant, perfect for FAQ sections, troubleshooting guides, or any content that poses questions to readers. See [docs](/components/callout.md). 18 | 19 | ```md 20 | !!!question Common Question 21 | How do I configure my documentation site? 22 | !!! 23 | ``` 24 | 25 | !!!question Common Question 26 | How do I configure my documentation site? 27 | !!! 28 | 29 | The `question` callout features a distinctive question mark icon and styling that makes it stand out from other callout types. 30 | 31 | ## Pipe separator image dimensions 32 | 33 | Set image dimensions using intuitive pipe separated syntax. See [docs](/components/image.md#dimensions). 34 | 35 | You can add a custom `width` or `width` x `height`: 36 | 37 | ```md 38 | ![Sample Image|300](/static/sample.jpg) 39 | ![Sample Image|300x200](/static/sample.jpg) 40 | ``` 41 | 42 | ![Sample Image|300](/static/sample.jpg) 43 | 44 | This syntax is cleaner than adding generic attributes and works seamlessly with Retype's image processing. 45 | 46 | Generic attributes on images are still supported and provide an alternative syntax for adding a custom `id`, CSS class, dimensions, or any custom attributes: 47 | 48 | ```md 49 | ![My image](image.jpg){.custom-css-class} 50 | ![My image](image.jpg){#custom-id} 51 | ![My image](image.jpg){#custom-id width="300"} 52 | ``` 53 | 54 | ## Printer friendly 55 | 56 | Retype now includes a comprehensive print stylesheet that help makes your documentation look great printed to PDF or paper. 57 | 58 | Clean Layout 59 | : Removes navigation, sidebars, and interactive elements 60 | 61 | Optimized Typography 62 | : Adjusts fonts and spacing for print readability 63 | 64 | Smart Page Breaks 65 | : Prevents awkward breaks in code blocks and tables 66 | 67 | URL Display 68 | : Shows full URLs for external links in print 69 | 70 | High Contrast 71 | : Ensures text is readable in black and white 72 | 73 | Simply use the browser's print function <kbd>Ctrl + p</kbd> or <kbd>⌘ + p</kbd> to get professional printed results. 74 | 75 | ## Navigation icon control 76 | 77 | Adjust your left sidebar navigation visual appearance with the new `nav.icons` setting. See [docs](/configuration/project.md#icons). 78 | 79 | !!! 80 | This feature is a [!badge Pro|info] only feature and a Retype [key](/pro/pro.md) is required to enable. 81 | !!! 82 | 83 | ```yaml 84 | nav: 85 | icons: 86 | mode: folders # Options: all, folders, pages, top, none 87 | ``` 88 | 89 | ![Show or Hide navigation icons](images/2025-05-28-nav-icon-mode.png) 90 | 91 | ### Modes 92 | 93 | | Mode | Description | 94 | |---------|------------------------------------------------------------------------| 95 | | `all` | Show icons for all navigation items (default) | 96 | | `folders` | Show icons only for folder/category items | 97 | | `pages` | Show icons only for page items | 98 | | `top` | Show icons only for top-level pages and folders, hide for nested items | 99 | | `none` | Hide all navigation icons for a clean, minimal look | 100 | 101 | This is particularly useful for documentation sites that prefer a cleaner, text-focused navigation. 102 | 103 | ## Dark or Light scheme 104 | 105 | Set your project's default color scheme with the new `scheme` configuration. See [docs](/configuration/project.md#scheme). 106 | 107 | !!! 108 | This feature is a [!badge Pro|info] only feature and a Retype [key](/pro/pro.md) is required to enable. 109 | !!! 110 | 111 | The `scheme` configuration allows you to control the default color mode (**light** or **dark**) for your Retype generated website. By default, Retype will automatically match the visitor's system preference, but now you can explicitly set the site to start in either `dark` or `light` mode. 112 | 113 | Add the following to your `retype.yml` file: 114 | 115 | ```yaml 116 | scheme: 117 | mode: dark # Options: system, dark, light 118 | ``` 119 | 120 | Mode | Description 121 | -- | -- 122 | `system` | (default) Automatically start using the visitor's system color scheme preference. 123 | `dark` | Start in dark mode. 124 | `light` | Start in light mode. 125 | 126 | The new `scheme` setting gives you control over the initial appearance while still allowing users to switch themes to match their preference. 127 | 128 | ## Migration made easy 129 | 130 | With universal [[callout]] syntax support, migrating from other documentation platforms is now seamless. Whether you're upgrading from Notion, GitHub, Obsidian, or any other platform, your existing callouts will work immediately in Retype. 131 | 132 | The enhanced image syntax and print support make Retype suitable for both digital and print documentation workflows, while the navigation customization options let you create the exact look you want. 133 | 134 | --- 135 | 136 | ## Write On! 137 | 138 | This release represents a major step forward in making Retype the most compatible and feature-rich documentation platform available. We're continuing to expand platform compatibility and add new features based on your feedback. 139 | 140 | Try out `v3.9` and experiment with the new features, then let us know what you think on [X](https://x.com/retypeapp) or by opening a GitHub [Issue](https://github.com/retypeapp/retype/issues). Your input helps shape the future of Retype. 141 | -------------------------------------------------------------------------------- /guides/themes.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: paintbrush 3 | nav: 4 | badge: NEW|info 5 | tags: [guide, pro] 6 | --- 7 | # Themes 8 | 9 | Retype's [`theme`](/configuration/project.md#theme) system allows you to customize the visual appearance of your website by overriding [[theme variables]]. With themes, you can adjust colors, spacing, typography, and other design elements to match your brand or project preferences. 10 | 11 | !!!base Pro Feature 12 | The theme functionality requires a [Retype Pro](/pro/pro.md) key or adding the following [`pro`](/configuration/project.md#pro) trial mode setting into your project `retype.yml` configuration file: 13 | 14 | ```yaml 15 | start 16 | pro: true 17 | ``` 18 | !!! 19 | 20 | ## Quick Start 21 | 22 | The quickest way to customize your site's appearance is by adding a `theme` configuration to your `retype.yml` file and setting a custom [`base-color`](/configuration/theme-variables.md#base-variables) theme variable. 23 | 24 | ```yml 25 | theme: 26 | base: 27 | base-color: "#8839ef" 28 | ``` 29 | 30 | ## Configuration Structure 31 | 32 | The theme configuration supports two main sections: 33 | 34 | ### `base` theme 35 | 36 | The [`base`](/configuration/project.md#theme) theme controls the light mode appearance and serves as the foundation for your project's visual style: 37 | 38 | ```yaml 39 | theme: 40 | base: 41 | base-color: "#8839ef" 42 | base-bg: "#eff1f5" 43 | base-link-weight: 500 44 | image-rounded: 0.75rem 45 | ``` 46 | 47 | ### `dark` theme 48 | 49 | The [`dark`](/configuration/project.md#theme-dark) theme specifically targets dark mode appearance. When the website is switched to dark mode, the dark theme variables override the [[#base-theme]] variables. The following demonstrates how to configure the `dark` theme variables: 50 | 51 | ```yaml 52 | theme: 53 | dark: 54 | base-color: "#ca9ee6" 55 | base-bg: "#303446" 56 | ``` 57 | 58 | ## Examples 59 | 60 | ### Brand Color Customization 61 | 62 | To match your brand colors: 63 | 64 | ```yml 65 | theme: 66 | base: 67 | base-color: "#ff6b35" # Orange brand color 68 | ``` 69 | 70 | ### Typography Adjustments 71 | 72 | To better match your project style and user-experience requirements: 73 | 74 | ```yml 75 | theme: 76 | base: 77 | base-link-weight: 500 # Slightly bolder links 78 | nav-item-text-active-weight: 700 # Bold active navigation 79 | heading-text: "#1a202c" # Darker headings 80 | ``` 81 | 82 | ### Dark Mode Optimization 83 | 84 | To adjust the dark mode: 85 | 86 | ```yml 87 | theme: 88 | dark: 89 | base-bg: "#0a0e1a" # Very dark blue background 90 | sidebar-left-bg: "#1a1f2e" # Slightly lighter sidebar 91 | base-text: "#e2e8f0" # Light grey text 92 | heading-text: "#ffffff" # Pure white headings 93 | base-border: "#2d3748" # Subtle borders 94 | ``` 95 | 96 | ### Component Styling 97 | 98 | To customize component colors and other elements: 99 | 100 | ```yml 101 | theme: 102 | base: 103 | # Rounded images 104 | image-rounded: 0.75rem 105 | 106 | # Custom variant colors 107 | primary: "#8caaee" # Blue 108 | success: "#a6d189" # Green 109 | danger: "#e78284" # Red 110 | warning: "#e5c890" # Yellow 111 | ``` 112 | 113 | ## Best Practices 114 | 115 | When customizing your Retype [theme](/configuration/project.md#theme), it’s best to start with small changes and gradually build up. Here are some guidelines to help you maintain a clean, accessible, and consistent design. 116 | 117 | ### 1. Start with the `base-color` 118 | 119 | Begin by tweaking a few brand colors before diving into full theme customization. This keeps things manageable and easier to approve before moving on to further theme refinements. 120 | 121 | ```yml 122 | theme: 123 | base: 124 | base-color: "#8839ef" #your-brand-color 125 | ``` 126 | 127 | ### 2. Prioritize readability and contrast 128 | 129 | Contrast between text and background is important for readability and accessibility. Avoid color combinations that are too similar and do not provide enough contrast. 130 | 131 | ```yml 132 | theme: 133 | base: 134 | base-text: "#4c4f69" # A strong neutral text color 135 | base-bg: "#ffffff" # Clean light background 136 | ``` 137 | 138 | !!!tip 139 | Use online contrast checkers to validate your color palette against WCAG standards. 140 | !!! 141 | 142 | ### 3. Check light and dark modes 143 | 144 | If you are customizing both the `base` and `dark` themes, be sure to test your changes in each mode. A color that works well in light mode might look washed out or harsh in dark mode, and require further refinement. 145 | 146 | ```yml 147 | theme: 148 | base: 149 | base-color: "#8839ef" 150 | dark: 151 | base-color: "#ca9ee6" 152 | ``` 153 | 154 | ### 4. Use Semantic variables where possible 155 | 156 | Instead of hardcoding colors everywhere, use the built-in semantic [[theme variables]]. It keeps your theme consistent and easier to maintain. 157 | 158 | ```yml 159 | theme: 160 | base: 161 | nav-item-text-active: "var(--base-500)" # Uses a consistent brand tone 162 | ``` 163 | 164 | Following these practices helps ensure your site looks good, stays accessible, and is easy to maintain as it grows. 165 | 166 | ## Troubleshooting 167 | 168 | ### Theme Not Applied 169 | 170 | - [x] Ensure you have a valid Retype Pro license or add [`start.pro: true`](/configuration/project.md#pro) 171 | - [x] Check that the syntax is correct in your `retype.yml` file 172 | - [x] Verify [theme variable](/configuration/theme-variables.md) names match exactly 173 | 174 | ### Dark Mode Issues 175 | 176 | - [x] Remember that `dark` theme variables only apply in dark mode 177 | - [x] Test with the theme switcher on your website 178 | - [x] Some variables may need both `base` and `dark` configured to provide proper contrast 179 | 180 | ### Variable Names 181 | 182 | - [x] All variable names use `kebab-case` (hyphens, not underscores) 183 | - [x] Variables are case-sensitive 184 | - [x] Don't include the `--` prefix in your configuration 185 | -------------------------------------------------------------------------------- /guides/github-actions.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: git-compare 3 | tags: 4 | - guide 5 | --- 6 | # GitHub Actions 7 | 8 | Add a simple GitHub Action to your project to automate the building and deployment of your Retype powered website. 9 | 10 | Currently, there are two Retype related GitHub Actions: 11 | 12 | 1. Retype [Build Action](https://github.com/retypeapp/action-build) 13 | 2. Retype [GitHub Pages Action](https://github.com/retypeapp/action-github-pages) 14 | 15 | The first, **Build Action** will automatically build your Retype powered website with each new change that is committed. 16 | 17 | The second, **GitHub Pages Action** will automatically publish your newly built website to a branch in Github so it is available to host from [GitHub Pages](https://pages.github.com/). By default, the `retype` branch is used, but of course that is also configurable. 18 | 19 | You can also deploy to many other hosting services, such as [[Cloudflare]], [[Docker]], [[GitLab Pages]], [[Netlify]], or your own web hosting or VPS provider. 20 | 21 | Automatically deploying to GitHub Pages requires a basic **retype-action.yml** configuration file to be added to your GitHub repo and some simple project configuration. 22 | 23 | !!! 24 | Content `write` permission are required so that Retype and can automatically create the `retype` branch and write the generated files into that branch. 25 | !!! 26 | --- 27 | 28 | ## Summary 29 | 30 | - [x] Add a **retype-action.yml** file, see [step 1](#step-1-add-retype-actionyml-workflow) 31 | - [x] Configure GitHub Pages, see [step 2](/hosting/github-pages.md#step-2-configure-github-pages) 32 | - [x] Set the branch to `retype`, see [branch config](/hosting/github-pages.md#pick-a-branch) 33 | - [x] Set the [`url`](/hosting/github-pages.md#set-a-url) 34 | - [x] More details on the Retype [Build Action](https://github.com/retypeapp/action-build). 35 | - [x] More details on the Retype [GitHub Pages Action](https://github.com/retypeapp/action-github-pages). 36 | 37 | All of these options are configurable and your specific requirements may vary. There is a lot of flexibility. Please check out the [Project Configuration](/configuration/project.md) options for full details. 38 | 39 | --- 40 | 41 | ## Step 1: Add **retype-action.yml** workflow 42 | 43 | Add the following **retype-action.yml** file to your GitHub project within the `.github/workflows/` folder. 44 | 45 | If the `.github/workflows/` folders do not exist within the root of your project, you can manually create the folders and they will be committed along with the **retype-action.yml**. 46 | 47 | ```yml .github/workflows/retype-action.yml 48 | name: Publish Retype powered website to GitHub Pages 49 | on: 50 | workflow_dispatch: 51 | push: 52 | branches: 53 | - main 54 | 55 | jobs: 56 | publish: 57 | runs-on: ubuntu-latest 58 | permissions: 59 | contents: write 60 | 61 | steps: 62 | - uses: actions/checkout@v4 63 | 64 | - uses: retypeapp/action-build@latest 65 | 66 | - uses: retypeapp/action-github-pages@latest 67 | with: 68 | update-branch: true 69 | ``` 70 | 71 | The above **retype-action.yml** workflow configuration instructs GitHub Actions to automatically build your website upon each commit to the `main` branch, and then deploy your new Retype powered website to a `retype` branch. 72 | 73 | If the `retype` branch is not available, the GitHub Action will automatically create the branch. 74 | 75 | If the default branch in your repo is `master`, change `- main` to `- master`. If the docs project was within a `docs` branch, change `- main` to `- docs`. The following snippet demonstrates setting the branch to `master`. 76 | 77 | ```yml 78 | push: 79 | branches: 80 | - master 81 | ``` 82 | 83 | Commit your **.github/workflows/retype-action.yml** file and push to your repo. 84 | 85 | ### RETYPE_KEY 86 | 87 | If your project requires a Retype key, that key can be configured by adding a [`RETYPE_KEY`](../configuration/envvars.md/#retype_key) secret to your repository settings and the corresponding `env` configuration to your project **.github/workflows/retype-action.yml** file. 88 | 89 | {%{ 90 | ```yml 91 | - uses: retypeapp/action-build@latest 92 | env: 93 | RETYPE_KEY: ${{ secrets.RETYPE_KEY }} 94 | ``` 95 | }%} 96 | 97 | !!!tip New Free GitHub Community Key 98 | Did you know there is a free Retype Pro Community Key for GitHub Pages hosting? Check it out on the [[Community]] page. 99 | !!! 100 | 101 | The following sample demonstrates a basic template to use for a workflow configuration file, if including the `RETYPE_KEY`: 102 | 103 | ```yml .github/workflows/retype-action.yml 104 | name: Publish Retype powered website to GitHub Pages 105 | on: 106 | workflow_dispatch: 107 | push: 108 | branches: 109 | - main 110 | 111 | jobs: 112 | publish: 113 | name: Publish to retype branch 114 | 115 | runs-on: ubuntu-latest 116 | 117 | permissions: 118 | contents: write 119 | 120 | steps: 121 | - uses: actions/checkout@v4 122 | 123 | - uses: retypeapp/action-build@latest 124 | env: 125 | RETYPE_KEY: {%{${{ secrets.RETYPE_KEY }}}%} 126 | 127 | - uses: retypeapp/action-github-pages@latest 128 | with: 129 | update-branch: true 130 | ``` 131 | 132 | ### RETYPE_PASSWORD 133 | 134 | If your project uses either [`protected`](/configuration/page.md#protected) or [`private`](/configuration/page.md#private) pages, adding a password for your visitors to use is required. 135 | 136 | {{ include "snippets/password-notice.md" }} 137 | 138 | A password can be configured by adding a [`RETYPE_PASSWORD`](../configuration/envvars.md/#retype_password) secret to your repository settings and the following `env` configuration to your project **.github/workflows/retype-action.yml** file. 139 | 140 | {%{ 141 | ```yml 142 | - uses: retypeapp/action-build@latest 143 | env: 144 | RETYPE_PASSWORD: ${{ secrets.RETYPE_PASSWORD }} 145 | ``` 146 | }%} 147 | 148 | If both the `RETYPE_KEY` and `RETYPE_PASSWORD` are needed, the configuration should be the following: 149 | 150 | {%{ 151 | ```yml 152 | - uses: retypeapp/action-build@latest 153 | env: 154 | RETYPE_KEY: ${{ secrets.RETYPE_KEY }} 155 | RETYPE_PASSWORD: ${{ secrets.RETYPE_PASSWORD }} 156 | ``` 157 | }%} 158 | 159 | --- 160 | 161 | ## Step 2: Configure GitHub Pages 162 | 163 | Once [Step 1](#step-1-add-retype-actionyml-workflow) is complete, now configure your [GitHub Pages](/hosting/github-pages.md) web site hosting. 164 | -------------------------------------------------------------------------------- /components/callout.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: info 3 | tags: [component] 4 | --- 5 | # Callout 6 | 7 | Callout components help to highlight important messages for the reader. 8 | 9 | To create an Callout, just surround a block of text or any markdown content with `!!!`. 10 | 11 | ```md 12 | !!! 13 | This is an Callout. 14 | !!! 15 | ``` 16 | 17 | !!! 18 | This is an Callout. 19 | !!! 20 | 21 | --- 22 | 23 | ## Title 24 | 25 | Callouts can also have titles. Add a space, then add your title, such as `!!! My title`. 26 | 27 | ```md 28 | !!! My title 29 | This is an Callout. 30 | !!! 31 | ``` 32 | 33 | !!! My title 34 | This is an Callout. 35 | !!! 36 | 37 | Some basic Markdown syntax and emoji `:shortcodes:` are supported in the titles. 38 | 39 | ```md 40 | !!! :zap: [Getting Started](/guides/getting-started.md) :zap: 41 | Get up to speed with Retype quickly by checking out the Getting Started guide. 42 | !!! 43 | ``` 44 | 45 | !!! :zap: [Getting Started](/guides/getting-started.md) :zap: 46 | Get up to speed with Retype quickly by checking out the Getting Started guide. 47 | !!! 48 | 49 | --- 50 | 51 | ## Variant 52 | 53 | Callouts come in nine different flavors which can be specified by passing a `variant` immediately after the `!!!`, such as `!!!danger`. 54 | 55 | | Variant | Color | 56 | | --- | --- | 57 | | `base` | Uses `base-color` | 58 | | `primary` (default) | `blue` | 59 | | `secondary` | `gray` | 60 | | `success` | `green` | 61 | | `tip` | `green` | 62 | | `danger` | `red` | 63 | | `warning` | `yellow` | 64 | | `info` | `light-blue` | 65 | | `question` | `purple` | 66 | | `light` | `light` | 67 | | `dark` | `dark` | 68 | | `ghost` | `light` or `dark` depending on time of day | 69 | | `contrast` | `dark` or `light` depending on time of day | 70 | 71 | --- 72 | 73 | ## Samples 74 | 75 | ``` 76 | !!!base Base 77 | This is a `base` Callout. 78 | !!! 79 | 80 | !!!primary Primary 81 | This is a `primary` Callout. 82 | !!! 83 | 84 | !!!secondary Secondary 85 | This is a `secondary` Callout. 86 | !!! 87 | 88 | !!!success Success 89 | This is a `success` Callout. 90 | !!! 91 | 92 | !!!tip Tip 93 | This is a `tip` Callout. 94 | !!! 95 | 96 | !!!danger Danger 97 | This is a `danger` Callout. 98 | !!! 99 | 100 | !!!warning Warning 101 | This is a `warning` Callout. 102 | !!! 103 | 104 | !!!info Info 105 | This is a `info` Callout. 106 | !!! 107 | 108 | !!!question Question 109 | This is a `question` Callout. 110 | !!! 111 | 112 | !!!light Light 113 | This is a `light` Callout. 114 | !!! 115 | 116 | !!!dark Dark 117 | This is a `dark` Callout. 118 | !!! 119 | 120 | !!!ghost Ghost 121 | This is a `ghost` Callout. 122 | !!! 123 | 124 | !!!contrast Contrast 125 | This is a `contrast` Callout. 126 | !!! 127 | ``` 128 | 129 | !!!base Base 130 | This is a `base` Callout. 131 | !!! 132 | 133 | !!!primary Primary 134 | This is a `primary` Callout. 135 | !!! 136 | 137 | !!!secondary Secondary 138 | This is a `secondary` Callout. 139 | !!! 140 | 141 | !!!success Success 142 | This is a `success` Callout. 143 | !!! 144 | 145 | !!!tip Tip 146 | This is a `tip` Callout. 147 | !!! 148 | 149 | !!!danger Danger 150 | This is a `danger` Callout. 151 | !!! 152 | 153 | !!!warning Warning 154 | This is a `warning` Callout. 155 | !!! 156 | 157 | !!!info Info 158 | This is a `info` Callout. 159 | !!! 160 | 161 | !!!question Question 162 | This is a `question` Callout. 163 | !!! 164 | 165 | !!!light Light 166 | This is a `light` Callout. 167 | !!! 168 | 169 | !!!dark Dark 170 | This is a `dark` Callout. 171 | !!! 172 | 173 | !!!ghost Ghost 174 | This is a `ghost` Callout. 175 | !!! 176 | 177 | !!!contrast Contrast 178 | This is a `contrast` Callout. 179 | !!! 180 | 181 | ## GitHub Alerts 182 | 183 | In addition to the Retype Callout component syntax options above, Retype also supports fully the GitHub [Alert](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts) extension which is an adaptation of the Markdown blockquote syntax. 184 | 185 | ```md 186 | > [!NOTE] 187 | > Useful information that users should know. 188 | 189 | > [!TIP] 190 | > Helpful advice for doing things better or more easily. 191 | 192 | > [!IMPORTANT] 193 | > Key information users need to know to achieve their goal. 194 | 195 | > [!WARNING] 196 | > Urgent info that needs immediate user attention to avoid problems. 197 | 198 | > [!CAUTION] 199 | > Advises about risks or negative outcomes of certain actions. 200 | ``` 201 | 202 | Here are the rendered GitHub Alerts: 203 | 204 | > [!NOTE] 205 | > Useful information that users should know. 206 | 207 | > [!TIP] 208 | > Helpful advice for doing things better or more easily. 209 | 210 | > [!IMPORTANT] 211 | > Key information users need to know to achieve their goal. 212 | 213 | > [!WARNING] 214 | > Urgent info that needs immediate user attention to avoid problems. 215 | 216 | > [!CAUTION] 217 | > Advises about risks or negative outcomes of certain actions. 218 | 219 | ### Custom title 220 | 221 | Retype also supports setting a custom title value on the GitHub Alerts using the following syntax: 222 | 223 | ```md 224 | > [!NOTE] Custom Title 225 | > Useful information that users should know. 226 | ``` 227 | 228 | > [!NOTE] Custom Title 229 | > Useful information that users should know. 230 | 231 | --- 232 | 233 | ## Theme variables 234 | 235 | Retype gives you full control over the look and feel of your callout components through customizable [[theme variables]]. 236 | 237 | You can override any of theme variable in your `retype.yml` configuration file using the `theme.base` and `theme.dark` settings. 238 | 239 | For example, to change the `primary` callout color for all instances of the `primary` callout within your project, add the following to your project's `retype.yml` file: 240 | 241 | ```yaml 242 | theme: 243 | base: 244 | # Revise the primary variant base color 245 | # across all components within the project 246 | # primary: "#209fb5" 247 | 248 | # Or, adjust callout only theme variables 249 | callout-primary: "#209fb5" 250 | ``` 251 | 252 | To learn more about theme variables and how they work across Retype, check out the [Themes Guide](/guides/themes.md), the [[Theme Variables]] documentation, and [`theme`](/configuration/project.md#theme) Project settings. 253 | 254 | !!! 255 | All callout theme variables can be customized in this way. The full list of available variables is shown below, and you can always refer to the [Callout Component](/configuration/theme-variables.md#callout-component) theme variables for the latest options. 256 | !!! -------------------------------------------------------------------------------- /components/button.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: play 3 | tags: [component] 4 | --- 5 | # Button 6 | 7 | Similar to a [Badge](badge.md), the Button component uses the same syntax as a hyperlink, but is prefixed with a `!button` identifier. 8 | 9 | ||| Demo 10 | [!button Button](button.md) 11 | 12 | [Normal link](button.md) 13 | ||| Source 14 | ```md 15 | [!button Button](button.md) 16 | 17 | [Normal link](button.md) 18 | ``` 19 | ||| 20 | 21 | --- 22 | 23 | ## Variant 24 | 25 | ```md 26 | // Text only (default Primary variant) 27 | [!button My Button] 28 | 29 | // Text with variant 30 | [!button variant="base" text="My Button"] 31 | 32 | // With link and variant 33 | [!button variant="primary" text="My Button"](https://retype.com/) 34 | ``` 35 | 36 | | Variant | Example | 37 | | --- | --- | 38 | | `base` | [!button variant="base" text="Base"] | 39 | | `primary` (default) | [!button variant="primary" text="Primary"] | 40 | | `secondary` | [!button variant="secondary" text="Secondary"] | 41 | | `success` | [!button variant="success" text="Success"] | 42 | | `danger` | [!button variant="danger" text="Danger"] | 43 | | `warning` | [!button variant="warning" text="Warning"] | 44 | | `info` | [!button variant="info" text="Info"] | 45 | | `light` | [!button variant="light" text="Light"] | 46 | | `dark` | [!button variant="dark" text="Dark"] | 47 | | `ghost` | [!button variant="ghost" text="Ghost"] | 48 | | `contrast` | [!button variant="contrast" text="Contrast"] | 49 | 50 | --- 51 | 52 | ## Corners 53 | 54 | ```md 55 | [!button text="Default"](button.md) 56 | [!button corners="square" text="Square"](button.md) 57 | [!button corners="pill" text="Button Pill"](button.md) 58 | ``` 59 | 60 | | Size | Example | 61 | | --- | --- | 62 | | `round` (default) | [!button text="Default"] | 63 | | `square` | [!button corners="square" text="Square"] | 64 | | `pill` | [!button corners="pill" text="Button Pill"] | 65 | 66 | --- 67 | 68 | ## Size 69 | 70 | ```md 71 | [!button size="m" text="Medium"](button.md) 72 | ``` 73 | 74 | | Size | Example | 75 | | --- | --- | 76 | | `xs` | [!button size="xs" text="XSmall"] | 77 | | `s` | [!button size="s" text="Small"] | 78 | | `m` (default) | [!button size="m" text="Medium"] | 79 | | `l` | [!button size="l" text="Large"] | 80 | | `xl` | [!button size="xl" text="XLarge"] | 81 | | `2xl` | [!button size="2xl" text="2XLarge"] | 82 | | `3xl` | [!button size="3xl" text="3XLarge"] | 83 | 84 | --- 85 | 86 | ## Target 87 | 88 | Sets the `target` attribute of the button and specifies which window or tab to open the link into. 89 | 90 | [!button target="blank" text="Retype"](https://retype.com/) 91 | 92 | ```md 93 | [!button target="blank" text="Retype"](https://retype.com/) 94 | ``` 95 | 96 | If no `target` is configured, the link will open in the current tab. 97 | 98 | 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. 99 | 100 | 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. 101 | 102 | Config `target` value | Runtime `target` value 103 | --- | --- 104 | `blank` | `_blank` 105 | `parent` | `_parent` 106 | `top` | `_top` 107 | `self` | `_self` 108 | `news1` | `news1` 109 | `nEWs2` | `news2` 110 | `recent NEWS` | `recent-news` 111 | 112 | See also the [`links.target`](/configuration/project.md#target) configuration. 113 | 114 | --- 115 | 116 | ## Icon and Emoji 117 | 118 | ### Octicons 119 | 120 | [Octicons](/components/octicons.md) can be used as an icon by settiing the `icon` property with the name of the Octicon. 121 | 122 | ```md 123 | [!button variant="info" icon="person" text="User"](button.md) 124 | [!button variant="primary" icon="paper-airplane" iconAlign="right" text="Send"](button.md) 125 | ``` 126 | 127 | [!button variant="info" icon="person" text="User" margin="0 8 0 0"] 128 | [!button variant="primary" icon="paper-airplane" iconAlign="right" text="Send"] 129 | 130 | ### Emoji 131 | 132 | Emoji `:shortcodes:` can be used for the icon. Please see [Mojee](https://mojeeio.github.io/Mojee//emojis) for a full list of supported Emoji shortcodes. 133 | 134 | ```md 135 | [!button variant="light" icon=":heart:" text="Like"](button.md) 136 | [!button variant="info" icon=":rocket:" iconAlign="right" text="Rocket"](button.md) 137 | ``` 138 | 139 | [!button variant="light" icon=":heart:" text="Like" margin="0 8 0 0"] 140 | [!button variant="info" icon=":rocket:" iconAlign="right" text="Rocket"] 141 | 142 | ### Image file 143 | 144 | Any image file can be used as the `icon`. 145 | 146 | ```md 147 | [!button icon="../static/retype-icon.svg"](button.md) 148 | ``` 149 | 150 | [!button icon="../static/retype-icon.svg"] 151 | 152 | ### SVG image 153 | 154 | The `icon` can also be set with an inline `<svg>` element. 155 | 156 | ``` 157 | [!button icon="<svg width="24" height="24"><path fill-rule="evenodd" d="M12 16.5a4.5 4.5 0 100-9 4.5 4.5 0 000 9zm0 1.5a6 6 0 100-12 6 6 0 000 12z"></path></svg>" text="Visit website"](button.md) 158 | ``` 159 | 160 | [!button icon="<svg width="24" height="24"><path fill-rule="evenodd" d="M12 16.5a4.5 4.5 0 100-9 4.5 4.5 0 000 9zm0 1.5a6 6 0 100-12 6 6 0 000 12z"></path></svg>" text="Visit website"] 161 | 162 | --- 163 | 164 | ## Theme variables 165 | 166 | Retype gives you full control over the look and feel of your button components through customizable [[theme variables]]. 167 | 168 | You can override any of theme variable in your `retype.yml` configuration file using the `theme.base` and `theme.dark` settings. 169 | 170 | For example, to change the `primary` button color and text color for all instances of the `primary` button within your project, add the following to your project's `retype.yml` file: 171 | 172 | ```yaml 173 | theme: 174 | base: 175 | # Revise the primary variant base color 176 | # across all components within the project 177 | # primary: "#209fb5" 178 | 179 | # Or, adjust button only theme variables 180 | button-primary: "#209fb5" 181 | button-primary-text: "#eff1f5" 182 | ``` 183 | 184 | To learn more about theme variables and how they work across Retype, check out the [Themes Guide](/guides/themes.md), the [[Theme Variables]] documentation, and [`theme`](/configuration/project.md#theme) Project settings. 185 | 186 | !!! 187 | All button theme variables can be customized in this way. Please refer to the [Button Component](/configuration/theme-variables.md#button-component) theme variables for the latest options. 188 | !!! -------------------------------------------------------------------------------- /blog/2025-05-04-whats-new-in-retype-v38.md: -------------------------------------------------------------------------------- 1 | --- 2 | authors: 3 | - name: "@geoffreymcgill" 4 | email: geoff@retype.com 5 | link: https://github.com/retypeapp 6 | category: 7 | - release 8 | --- 9 | # What's New in Retype v3.8 10 | 11 | ![](images/2025-05-04.png) 12 | 13 | Retype v3.8 introduces powerful new linking capabilities, enhanced search functionality, and improved content management features. This release focuses on making documentation more interconnected and discoverable while adding modern conveniences for content creators. 14 | 15 | ## Stack navigation mode 16 | 17 | New navigation mode that transforms your top-level folders into visually distinct stacked blocks. This feature is perfect for complex documentation sites that need better organization and visual hierarchy. 18 | 19 | !!! 20 | This feature is a [!badge Pro|info] only feature and a Retype [key](/pro/pro.md) is required to enable. 21 | !!! 22 | 23 | ### Project configuration 24 | 25 | Enable stack mode for all top-level folders in your project by adding the following setting to your project `retype.yml` file. See [docs](/configuration/project.md#nav-mode). 26 | 27 | ```yaml retype.yml 28 | nav: 29 | mode: stack 30 | ``` 31 | 32 | This transforms your entire navigation structure, making top-level sections more prominent and easier to distinguish. 33 | 34 | ### Page configuration 35 | 36 | You can also enable stack mode for specific folders by adding the same setting into a `index.yml` file within your folder. See [docs](/configuration/page.md#nav-mode). 37 | 38 | ```yaml index.yml 39 | --- 40 | nav: 41 | mode: stack 42 | --- 43 | ``` 44 | 45 | ### How It Works 46 | 47 | Stack mode only applies to top-level folders that contain child pages. When enabled: 48 | 49 | - Top-level folders are rendered as distinct visual blocks 50 | - Each stack block contains the folder's child pages 51 | - The layout provides better visual separation between major sections 52 | - Navigation becomes more scannable for large documentation sites 53 | 54 | ### Requirements 55 | 56 | - Stack mode requires a Retype [[Pro]] key 57 | - Only works on top-level folders (not nested subfolders) 58 | - Folders must contain child pages to be rendered as stacks 59 | 60 | This feature is particularly useful for documentation sites with multiple product lines, different user types, or distinct content categories that benefit from clear visual separation. 61 | 62 | ## WikiLinks Support 63 | 64 | Another big new feature in v3.8 is comprehensive WikiLink syntax support, bringing wiki-style linking to Retype. This makes it easier to create interconnected documentation with flexible, forgiving link resolution. 65 | 66 | ### Basic WikiLinks 67 | 68 | Create links using double square brackets: 69 | 70 | ```markdown 71 | Check out the Retype [[Getting Started]] guide. 72 | 73 | The same link using Markdown would be [Getting Started](/guides/getting-started.md). 74 | ``` 75 | 76 | Check out the Retype [[Getting Started]] guide. 77 | 78 | Retype automatically resolves these links even if the exact filename does not match. Retype intelligently handles variations in naming, making your links more resilient to file renames and reorganization. 79 | 80 | ### WikiLinks with Custom Labels 81 | 82 | Provide custom link text using the pipe syntax: 83 | 84 | ```markdown 85 | Read our [[installation-guide|Installation Guide]] to get started. 86 | ``` 87 | 88 | ### Image WikiLinks 89 | 90 | Embed images using the same syntax: 91 | 92 | ```markdown 93 | ![[sample.jpg]] 94 | ![[sample.jpg|Sample image]] 95 | ``` 96 | 97 | ![[sample.jpg|Sample image]] 98 | 99 | ### Anchor Links 100 | 101 | Link to specific sections within pages: 102 | 103 | ```markdown 104 | [[troubleshooting#common-issues]] 105 | [[#local-section]] <!-- Same page anchor --> 106 | ``` 107 | 108 | WikiLinks use intelligent resolution that can find pages even when the link doesn't exactly match the filename, making your documentation more maintainable. 109 | 110 | ## YouTube Auto-Embedding 111 | 112 | Retype now automatically converts YouTube URLs into embedded video players. Simply paste a YouTube URL on its own line. See [docs](/components/youtube.md). 113 | 114 | ```markdown 115 | https://www.youtube.com/watch?v=dQw4w9WgXcQ 116 | ``` 117 | 118 | https://www.youtube.com/watch?v=dQw4w9WgXcQ 119 | 120 | This becomes a fully responsive, embedded video player with proper styling and controls. 121 | 122 | ### Supported YouTube Formats 123 | 124 | Retype recognises all common YouTube URL formats: 125 | 126 | - `https://www.youtube.com/watch?v=VIDEO_ID` 127 | - `https://youtu.be/VIDEO_ID` 128 | - `https://www.youtube.com/embed/VIDEO_ID` 129 | - URLs with timestamps: `https://www.youtube.com/watch?v=VIDEO_ID&t=120s` 130 | - Playlist URLs with additional parameters 131 | 132 | ## Home.md Support 133 | 134 | You can now use `home.md` as your project's home page, providing another option alongside the existing `readme.md`, `index.md`, `default.md`, and `welcome.md` files. 135 | 136 | ```md home.md 137 | # Welcome Home 138 | 139 | This is your project's home page using home.md. 140 | ``` 141 | 142 | This gives you more flexibility in organising your content and aligns with common documentation conventions. 143 | 144 | ## Automatic Search Language Detection 145 | 146 | Retype now automatically detects the languages used in your content and optimises search accordingly. This happens behind the scenes without any configuration needed. 147 | 148 | ### How It Works 149 | 150 | The language detection system: 151 | - Analyses your content to identify languages used 152 | - Automatically includes appropriate search language packs 153 | - Supports over 25 languages including English, Spanish, French, German, Japanese, Chinese, Arabic, and many more 154 | - Improves search accuracy for multilingual documentation 155 | 156 | ### Manual Configuration 157 | 158 | You can still manually configure search languages if needed: 159 | 160 | ```yaml 161 | search: 162 | languages: 163 | - en 164 | - es 165 | - fr 166 | - "*" # Enable auto-detection alongside manual languages 167 | ``` 168 | 169 | The `"*"` token enables auto-detection while keeping your manually specified languages. 170 | 171 | ## Enhanced Include Functionality 172 | 173 | The `include` feature now supports accessing files outside of your project directory, giving you more flexibility in content organization: 174 | 175 | {%{ 176 | ```md /docs/readme.md 177 | {{ include "../readme.md" }} 178 | ``` 179 | }%} 180 | 181 | This is particularly useful for grabbing the `readme.md` outside of your documentation directory. 182 | 183 | ## Greek and Hebrew Language Support 184 | 185 | Retype now includes full support for Greek and Hebrew languages, including: 186 | - Proper text rendering and direction 187 | - Search functionality optimised for these languages 188 | - UI translations where applicable 189 | 190 | --- 191 | 192 | ## Write On! 193 | 194 | All existing Retype features continue to work exactly as before. The new WikiLinks feature works alongside traditional Markdown links, so you can adopt it gradually or use both approaches as needed. 195 | 196 | Try out `v3.8` and experiment with the new features, then let us know what you think on [X](https://x.com/retypeapp) or by opening a GitHub [Issue](https://github.com/retypeapp/retype/issues). Your input helps shape the future of Retype. 197 | -------------------------------------------------------------------------------- /components/badge.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: id-badge 3 | tags: [component] 4 | --- 5 | # Badge 6 | 7 | Similar to a [Button](button.md), the Badge component uses the same syntax as a hyperlink, but is prefixed with a `!badge` identifier. 8 | 9 | ||| Demo 10 | [!badge Badge](badge.md) 11 | 12 | [Normal link](badge.md) 13 | ||| Source 14 | ```md 15 | [!badge Badge](badge.md) 16 | 17 | [Normal link](badge.md) 18 | ``` 19 | ||| 20 | 21 | With the Badge component, the link is optional and can be omitted. 22 | 23 | ||| Demo 24 | [!badge Badge] 25 | ||| Source 26 | ```md 27 | [!badge Badge] 28 | ``` 29 | ||| 30 | 31 | --- 32 | 33 | ## Variant 34 | 35 | ```md 36 | // Text only (default Primary variant) 37 | [!badge My Badge] 38 | 39 | // Text with variant 40 | [!badge variant="base" text="My Badge"] 41 | 42 | // With link and variant 43 | [!badge variant="primary" text="My Badge"](https://retype.com/) 44 | ``` 45 | 46 | | Variant | Text only | With link | 47 | | --- | --- | --- | 48 | | `base` | [!badge variant="base" text="Base"] | [!badge variant="base" text="Base"](#variant) | 49 | | `primary` (default) | [!badge variant="primary" text="Primary"] | [!badge variant="primary" text="Primary"](#variant) | 50 | | `secondary` | [!badge variant="secondary" text="Secondary"] | [!badge variant="secondary" text="Secondary"](#variant) | 51 | | `success` | [!badge variant="success" text="Success"] | [!badge variant="success" text="Success"](#variant) | 52 | | `danger` | [!badge variant="danger" text="Danger"] | [!badge variant="danger" text="Danger"](#variant) | 53 | | `warning` | [!badge variant="warning" text="Warning"] | [!badge variant="warning" text="Warning"](#variant) | 54 | | `info` | [!badge variant="info" text="Info"] | [!badge variant="info" text="Info"](#variant) | 55 | | `light` | [!badge variant="light" text="Light"] | [!badge variant="light" text="Light"](#variant) | 56 | | `dark` | [!badge variant="dark" text="Dark"] | [!badge variant="dark" text="Dark"](#variant) | 57 | | `ghost` | [!badge variant="ghost" text="Ghost"] | [!badge variant="ghost" text="Ghost"](#variant) | 58 | | `contrast` | [!badge variant="contrast" text="Contrast"] | [!badge variant="contrast" text="Contrast"](#variant) | 59 | 60 | --- 61 | 62 | ## Corners 63 | 64 | ```md 65 | [!badge text="Default"] 66 | [!badge corners="square" text="Square"] 67 | [!badge corners="pill" text="Button Pill"] 68 | ``` 69 | 70 | | Size | Example | 71 | | --- | --- | 72 | | `round` (default) | [!badge text="Default"] | 73 | | `square` | [!badge corners="square" text="Square"] | 74 | | `pill` | [!badge corners="pill" text="Button Pill"] | 75 | 76 | --- 77 | 78 | ## Size 79 | 80 | ```md 81 | [!badge size="m" text="Medium"] 82 | ``` 83 | 84 | | Size | Example | 85 | | --- | --- | 86 | | `xs` | [!badge size="xs" text="XSmall"] | 87 | | `s` | [!badge size="s" text="Small"] | 88 | | `m` (default) | [!badge size="m" text="Medium"] | 89 | | `l` | [!badge size="l" text="Large"] | 90 | | `xl` | [!badge size="xl" text="XLarge"] | 91 | | `2xl` | [!badge size="2xl" text="2XLarge"] | 92 | | `3xl` | [!badge size="3xl" text="3XLarge"] | 93 | 94 | --- 95 | 96 | ## Target 97 | 98 | Sets the `target` attribute of the badge and specifies which window or tab to open the link into. 99 | 100 | [!badge target="blank" text="Retype"](https://retype.com/) 101 | 102 | ```md 103 | [!badge target="blank" text="Retype"](https://retype.com/) 104 | ``` 105 | 106 | If no `target` is configured, the link will open in the current tab. 107 | 108 | 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. 109 | 110 | 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. 111 | 112 | Config `target` value | Runtime `target` value 113 | --- | --- 114 | `blank` | `_blank` 115 | `parent` | `_parent` 116 | `top` | `_top` 117 | `self` | `_self` 118 | `news1` | `news1` 119 | `nEWs2` | `news2` 120 | `recent NEWS` | `recent-news` 121 | 122 | See also the [`links.target`](/configuration/project.md#target) configuration. 123 | 124 | --- 125 | 126 | ## Icon and Emoji 127 | 128 | ### Octicons 129 | 130 | [Octicons](/components/octicons.md) can be used as an icon by settiing the `icon` property with the name of the Octicon. 131 | 132 | ```md 133 | [!badge variant="info" icon="person" text="User" margin="0 8 0 0"] 134 | [!badge variant="primary" icon="paper-airplane" iconAlign="right" text="Send"] 135 | ``` 136 | 137 | [!badge variant="info" icon="person" text="User" margin="0 8 0 0"] 138 | [!badge variant="primary" icon="paper-airplane" iconAlign="right" text="Send"] 139 | 140 | ### Emoji 141 | 142 | Emoji `:shortcodes:` can be used for the icon. Please see [Mojee](https://mojeeio.github.io/Mojee//emojis) for a full list of supported Emoji shortcodes. 143 | 144 | ```md 145 | [!badge variant="light" icon=":heart:" text="Like"] 146 | [!badge variant="info" icon=":rocket:" iconAlign="right" text="Rocket"] 147 | ``` 148 | 149 | [!badge variant="light" icon=":heart:" text="Like" margin="0 8 0 0"] 150 | [!badge variant="info" icon=":rocket:" iconAlign="right" text="Rocket"] 151 | 152 | ### Image file 153 | 154 | Any image file can be used as the `icon`. 155 | 156 | ```md 157 | [!badge icon="../static/retype-icon.svg"] 158 | ``` 159 | 160 | [!badge icon="../static/retype-icon.svg"] 161 | 162 | ### SVG image 163 | 164 | The `icon` can also be set with an inline `<svg>` element. 165 | 166 | ``` 167 | [!badge icon="<svg width="24" height="24"><path fill-rule="evenodd" d="M12 16.5a4.5 4.5 0 100-9 4.5 4.5 0 000 9zm0 1.5a6 6 0 100-12 6 6 0 000 12z"></path></svg>" text="Visit website"](badge.md) 168 | ``` 169 | 170 | [!badge icon="<svg width="24" height="24"><path fill-rule="evenodd" d="M12 16.5a4.5 4.5 0 100-9 4.5 4.5 0 000 9zm0 1.5a6 6 0 100-12 6 6 0 000 12z"></path></svg>" text="Visit website"](badge.md) 171 | 172 | --- 173 | 174 | ## Theme variables 175 | 176 | Retype gives you full control over the look and feel of your badge components through customizable [[theme variables]]. 177 | 178 | You can override any of theme variable in your `retype.yml` configuration file using the `theme.base` and `theme.dark` settings. 179 | 180 | For example, to change the `primary` badge color and text color for all instances of the `primary` badge within your project, add the following to your project's `retype.yml` file: 181 | 182 | ```yaml 183 | theme: 184 | base: 185 | # Revise the primary variant base color 186 | # across all components within the project 187 | # primary: "#209fb5" 188 | 189 | # Or, adjust badge only theme variables 190 | badge-primary: "#209fb5" 191 | badge-primary-text: "#eff1f5" 192 | ``` 193 | 194 | To learn more about theme variables and how they work across Retype, check out the [Themes Guide](/guides/themes.md), the [[Theme Variables]] documentation, and [`theme`](/configuration/project.md#theme) Project settings. 195 | 196 | !!! 197 | All badge theme variables can be customized in this way. The full list of available variables is shown below, and you can always refer to the [Badge Component](/configuration/theme-variables.md#badge-component) theme variables for the latest options. 198 | !!! 199 | -------------------------------------------------------------------------------- /components/image.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: image 3 | tags: [component] 4 | --- 5 | # Image 6 | 7 | The image component embeds an image in your document. You can point to image files stored within the project, or an external URL. 8 | 9 | Checkout the [Markdown Guide](https://www.markdownguide.org/basic-syntax/#images-1) for more details on configuring images. 10 | 11 | --- 12 | 13 | ## Basic syntax 14 | 15 | To add an image to your document, a similar syntax to links is used but prefixed with an exclamation mark `!`. 16 | 17 | ```md 18 | ![](/static/sample.jpg) 19 | ``` 20 | 21 | ![](/static/sample.jpg) 22 | 23 | --- 24 | 25 | ## Optional caption 26 | 27 | An optional caption below the image can be set by adding your caption text between the `[]` brackets. The following sample demonstrates adding a caption: 28 | 29 | ```md 30 | ![This is an optional caption](/static/sample.jpg) 31 | ``` 32 | 33 | ![This is an optional caption](/static/sample.jpg) 34 | 35 | --- 36 | 37 | ## Optional title 38 | 39 | An optional `title` attribute for the resulting HTML `<img>` element can be set by adding the title text after the link. The title can be used differently within different browsers, but is typically shown as a tooltip when mouse pointer is held over the image. The following sample demonstrates adding a title: 40 | 41 | ```md 42 | ![This is an optional caption](/static/sample.jpg "This is an optional title") 43 | ``` 44 | 45 | Hold your mouse pointer over the image to see the title. 46 | 47 | ![This is an optional caption](/static/sample.jpg "This is an optional title") 48 | 49 | --- 50 | 51 | ## Links 52 | 53 | By default, images are not links, but it's easy to make your image into a link by just wrapping the image in a link. 54 | 55 | You can link to an external (see outbound) location or any page within your project. 56 | 57 | The following demonstrates adding an outbound link to an image: 58 | 59 | ```md 60 | [![](/static/sample.jpg)](https://retype.com) 61 | ``` 62 | 63 | [![](/static/sample.jpg)](https://retype.com) 64 | 65 | The following demonstrates adding an outbound link to another page: 66 | 67 | ```md 68 | [![](/static/sample.jpg)](/guides/getting-started.md) 69 | ``` 70 | 71 | [![](/static/sample.jpg)](/guides/getting-started.md) 72 | 73 | --- 74 | 75 | ## Dimensions 76 | 77 | You can control the size of your images by specifying custom dimensions using the pipe `|` separator followed by width and/or height values. 78 | 79 | ### Setting width and height 80 | 81 | To set both width and height, use the format `widthxheight` after the pipe separator: 82 | 83 | ```md 84 | ![Sample Image|300x200](/static/sample.jpg) 85 | ``` 86 | 87 | ![Sample Image|300x200](/static/sample.jpg) 88 | 89 | ### Setting width only 90 | 91 | To set only the width, specify a single number after the pipe separator. The image will automatically scale its height to maintain the original aspect ratio: 92 | 93 | ```md 94 | ![Sample Image|300](/static/sample.jpg) 95 | ``` 96 | 97 | ![Sample Image|300](/static/sample.jpg) 98 | 99 | !!! 100 | The dimensions are specified in pixels. For best results, use values that maintain the image's original aspect ratio to prevent distortion. 101 | !!! 102 | 103 | --- 104 | 105 | ## Generic Attributes 106 | 107 | Retype allows you to add custom HTML attributes to your images using a simple curly brace syntax `{}`. This powerful feature lets you customize the appearance and behavior of your images beyond basic Markdown capabilities. 108 | 109 | ### Custom `id` 110 | 111 | Add a unique identifier to your image for styling or JavaScript targeting. The `id` attribute is prefixed with a `#` symbol. 112 | 113 | ```md 114 | ![](/static/sample.jpg){#custom-id} 115 | 116 | // Creates the following HTML 117 | <img src="/static/sample.jpg" id="custom-id"> 118 | ``` 119 | 120 | ![](/static/sample.jpg){#custom-id} 121 | 122 | ### Custom CSS class 123 | 124 | Apply CSS classes to your image for styling. Class names are prefixed with a `.` dot. You can add multiple classes by separating them with spaces. 125 | 126 | ```md 127 | ![](/static/sample.jpg){.rounded-lg} 128 | 129 | // Creates the following HTML 130 | <img src="/static/sample.jpg" class="rounded-lg"> 131 | ``` 132 | 133 | ![](/static/sample.jpg){.rounded-lg} 134 | 135 | ### Custom width or height 136 | 137 | Set specific dimensions for your image using the `width` and `height` attributes. Values can be specified in pixels (px) or other CSS units. 138 | 139 | ```md 140 | ![](/static/sample.jpg){width="300" height="200"} 141 | 142 | // Creates the following HTML 143 | <img src="/static/sample.jpg" width="300" height="200"> 144 | ``` 145 | 146 | ![](/static/sample.jpg){width="300" height="200"} 147 | 148 | ### Custom CSS class and width 149 | 150 | Combine CSS classes with specific dimensions to create perfectly styled images. 151 | 152 | ```md 153 | ![](/static/sample.jpg){.rounded-lg width="300"} 154 | 155 | // Creates the following HTML 156 | <img src="/static/sample.jpg" class="rounded-lg" width="300"> 157 | ``` 158 | 159 | ![](/static/sample.jpg){.rounded-lg width="300"} 160 | 161 | ### Custom data attributes 162 | 163 | Add custom data attributes to your images for JavaScript functionality or additional metadata. Data attributes are created using the `data-*` naming convention. 164 | 165 | ```md 166 | ![](/static/sample.jpg){data-location="Korea"} 167 | 168 | // Creates the following HTML 169 | <img src="/static/sample.jpg" data-location="Korea" /> 170 | ``` 171 | 172 | ![](/static/sample.jpg){data-location="Korea"} 173 | 174 | !!! 175 | You can combine multiple attributes in a single set of curly braces. For example: `![](/static/sample.jpg){.rounded-lg width="300" data-location="Korea"}`. 176 | !!! 177 | 178 | --- 179 | 180 | ## Alignment options 181 | 182 | If an image is configured on a separate line, Retype includes extra functionality for the custom alignment of images on the page. For instance, you can specify the left or right alignment of an image and have the text flow around the image. Check out the [Image alignment :icon-image:](image-alignment-demo.md) demo. 183 | 184 | !!! 185 | If an image is defined inline with other text on the same line, the image will be treated as an inline image and the following Retype alignment options will be ignored. 186 | !!! 187 | 188 | An additional **plus** option for Blog pages or pages with `layout: central` will help to position the image slightly overlapping the left or right content margins. 189 | 190 | Position | Markdown | Description 191 | --- | --- | --- 192 | `center` | `![Caption](photo.jpg)` | Center aligned in its container (default) 193 | `left` | `-![Caption](photo.jpg)` | Float left aligned 194 | `leftplus` | `--![Caption](photo.jpg)` | Float left aligned with some negative left offset 195 | `right` | `![Caption](photo.jpg)-` | Float right aligned 196 | `rightplus` | `![Caption](photo.jpg)--` | Float right aligned with some negative right offset 197 | `centerplus` | `--![Caption](photo.jpg)--` | Center aligned plus negative offset both sides 198 | 199 | Check out the following sample page demonstrating all the image alignment scenarios, including **plus** options: 200 | 201 | [!ref Image alignment demo](image-alignment-demo.md) 202 | 203 | The **plus** alignment options only apply when the page is `layout: central` or `layout: blog`. 204 | 205 | For default page layouts with a left navigation and/or the right table of contents, the **plus** positions will fallback to their non-plus equivalents. For instance, `rightplus` will fallback to `right` and the `centerplus` will fallback to `center`. 206 | 207 | Photo credits to [carlos aranda](https://unsplash.com/@carlosaranda). -------------------------------------------------------------------------------- /_includes/data/octicons.md: -------------------------------------------------------------------------------- 1 | {{~ 2 | octicons_new = [ 3 | "sparkle" 4 | ] 5 | 6 | octicons = [ 7 | "accessibility", 8 | "accessibility-inset", 9 | "ai-model", 10 | "alert", 11 | "alert-fill", 12 | "apps", 13 | "archive", 14 | "arrow-both", 15 | "arrow-down", 16 | "arrow-down-left", 17 | "arrow-down-right", 18 | "arrow-left", 19 | "arrow-right", 20 | "arrow-switch", 21 | "arrow-up", 22 | "arrow-up-left", 23 | "arrow-up-right", 24 | "beaker", 25 | "bell", 26 | "bell-fill", 27 | "bell-slash", 28 | "blocked", 29 | "bold", 30 | "book", 31 | "bookmark", 32 | "bookmark-fill", 33 | "bookmark-filled", 34 | "bookmark-slash", 35 | "bookmark-slash-fill", 36 | "briefcase", 37 | "broadcast", 38 | "browser", 39 | "bug", 40 | "cache", 41 | "calendar", 42 | "check", 43 | "check-circle", 44 | "check-circle-fill", 45 | "checkbox", 46 | "checklist", 47 | "chevron-down", 48 | "chevron-left", 49 | "chevron-right", 50 | "chevron-up", 51 | "circle", 52 | "circle-slash", 53 | "clock", 54 | "clock-fill", 55 | "cloud", 56 | "cloud-offline", 57 | "code", 58 | "code-of-conduct", 59 | "code-review", 60 | "code-square", 61 | "codescan", 62 | "codescan-checkmark", 63 | "codespaces", 64 | "columns", 65 | "command-palette", 66 | "comment", 67 | "comment-discussion", 68 | "container", 69 | "copilot", 70 | "copilot-error", 71 | "copilot-warning", 72 | "copy", 73 | "cpu", 74 | "credit-card", 75 | "cross-reference", 76 | "dash", 77 | "database", 78 | "dependabot", 79 | "desktop-download", 80 | "device-camera", 81 | "device-camera-video", 82 | "device-desktop", 83 | "device-mobile", 84 | "devices", 85 | "diamond", 86 | "diff", 87 | "diff-added", 88 | "diff-ignored", 89 | "diff-modified", 90 | "diff-removed", 91 | "diff-renamed", 92 | "discussion-closed", 93 | "discussion-duplicate", 94 | "discussion-outdated", 95 | "dot", 96 | "dot-fill", 97 | "download", 98 | "duplicate", 99 | "ellipsis", 100 | "eye", 101 | "eye-closed", 102 | "feed-discussion", 103 | "feed-forked", 104 | "feed-heart", 105 | "feed-issue-closed", 106 | "feed-issue-draft", 107 | "feed-issue-open", 108 | "feed-issue-reopen", 109 | "feed-merged", 110 | "feed-person", 111 | "feed-plus", 112 | "feed-public", 113 | "feed-pull-request-closed", 114 | "feed-pull-request-draft", 115 | "feed-pull-request-open", 116 | "feed-repo", 117 | "feed-rocket", 118 | "feed-star", 119 | "feed-tag", 120 | "feed-trophy", 121 | "file", 122 | "file-added", 123 | "file-badge", 124 | "file-binary", 125 | "file-code", 126 | "file-diff", 127 | "file-directory", 128 | "file-directory-fill", 129 | "file-directory-open-fill", 130 | "file-directory-symlink", 131 | "file-media", 132 | "file-moved", 133 | "file-removed", 134 | "file-submodule", 135 | "file-symlink-file", 136 | "file-zip", 137 | "filter", 138 | "filter-remove", 139 | "fiscal-host", 140 | "flame", 141 | "fold", 142 | "fold-down", 143 | "fold-up", 144 | "gear", 145 | "gift", 146 | "git-branch", 147 | "git-commit", 148 | "git-compare", 149 | "git-merge", 150 | "git-merge-queue", 151 | "git-pull-request", 152 | "git-pull-request-closed", 153 | "git-pull-request-draft", 154 | "globe", 155 | "goal", 156 | "grabber", 157 | "graph", 158 | "hash", 159 | "heading", 160 | "heart", 161 | "heart-fill", 162 | "history", 163 | "home", 164 | "home-fill", 165 | "horizontal-rule", 166 | "hourglass", 167 | "hubot", 168 | "id-badge", 169 | "image", 170 | "inbox", 171 | "infinity", 172 | "info", 173 | "issue-closed", 174 | "issue-draft", 175 | "issue-opened", 176 | "issue-reopened", 177 | "issue-tracked-by", 178 | "issue-tracks", 179 | "italic", 180 | "iterations", 181 | "kebab-horizontal", 182 | "key", 183 | "key-asterisk", 184 | "law", 185 | "light-bulb", 186 | "link", 187 | "link-external", 188 | "list-ordered", 189 | "list-unordered", 190 | "location", 191 | "lock", 192 | "log", 193 | "logo-gist", 194 | "logo-github", 195 | "mail", 196 | "mark-github", 197 | "markdown", 198 | "megaphone", 199 | "mention", 200 | "meter", 201 | "milestone", 202 | "mirror", 203 | "moon", 204 | "mortar-board", 205 | "move-to-bottom", 206 | "move-to-end", 207 | "move-to-start", 208 | "move-to-top", 209 | "multi-select", 210 | "mute", 211 | "no-entry", 212 | "north-star", 213 | "note", 214 | "number", 215 | "organization", 216 | "package", 217 | "package-dependencies", 218 | "package-dependents", 219 | "paintbrush", 220 | "paper-airplane", 221 | "paperclip", 222 | "passkey-fill", 223 | "paste", 224 | "pause", 225 | "pencil", 226 | "people", 227 | "person", 228 | "person-add", 229 | "person-fill", 230 | "pin", 231 | "pin-slash", 232 | "pivot-column", 233 | "play", 234 | "plug", 235 | "plus", 236 | "plus-circle", 237 | "project", 238 | "project-roadmap", 239 | "project-symlink", 240 | "project-template", 241 | "pulse", 242 | "question", 243 | "quote", 244 | "read", 245 | "redo", 246 | "rel-file-path", 247 | "reply", 248 | "repo", 249 | "repo-clone", 250 | "repo-delete", 251 | "repo-deleted", 252 | "repo-forked", 253 | "repo-locked", 254 | "repo-pull", 255 | "repo-push", 256 | "repo-template", 257 | "report", 258 | "rocket", 259 | "rows", 260 | "rss", 261 | "ruby", 262 | "screen-full", 263 | "screen-normal", 264 | "search", 265 | "server", 266 | "share", 267 | "share-android", 268 | "shield", 269 | "shield-check", 270 | "shield-lock", 271 | "shield-slash", 272 | "shield-x", 273 | "sidebar-collapse", 274 | "sidebar-expand", 275 | "sign-in", 276 | "sign-out", 277 | "single-select", 278 | "skip", 279 | "skip-fill", 280 | "sliders", 281 | "smiley", 282 | "sort-asc", 283 | "sort-desc", 284 | "sparkle", 285 | "sparkle-fill", 286 | "sparkles-fill", 287 | "sponsor-tiers", 288 | "square", 289 | "square-circle", 290 | "square-fill", 291 | "squirrel", 292 | "stack", 293 | "star", 294 | "star-fill", 295 | "stop", 296 | "stopwatch", 297 | "strikethrough", 298 | "sun", 299 | "sync", 300 | "tab", 301 | "tab-external", 302 | "table", 303 | "tag", 304 | "tasklist", 305 | "telescope", 306 | "telescope-fill", 307 | "terminal", 308 | "three-bars", 309 | "thumbsdown", 310 | "thumbsup", 311 | "tools", 312 | "tracked-by-closed-completed", 313 | "tracked-by-closed-not-planned", 314 | "trash", 315 | "triangle-down", 316 | "triangle-left", 317 | "triangle-right", 318 | "triangle-up", 319 | "trophy", 320 | "typography", 321 | "undo", 322 | "unfold", 323 | "unlink", 324 | "unlock", 325 | "unmute", 326 | "unread", 327 | "unverified", 328 | "upload", 329 | "verified", 330 | "versions", 331 | "video", 332 | "webhook", 333 | "workflow", 334 | "x", 335 | "x-circle", 336 | "x-circle-fill", 337 | "zap", 338 | "zoom-in", 339 | "zoom-out", 340 | ] 341 | ~}} -------------------------------------------------------------------------------- /components/code-block.md: -------------------------------------------------------------------------------- 1 | --- 2 | icon: code-square 3 | tags: [component] 4 | --- 5 | # Code Block 6 | 7 | Blocks of code or any preformatted text can be displayed by wrapping with triple backticks characters before and after. 8 | 9 | ||| :icon-code: Source 10 | ~~~ 11 | ``` 12 | A basic code block 13 | ``` 14 | ~~~ 15 | ||| :icon-play: Demo 16 | ``` 17 | A basic code block 18 | ``` 19 | ||| 20 | 21 | --- 22 | 23 | ## Syntax highlighting 24 | 25 | Optional syntax highlighting of the code within the code block can be configured by adding a language identifier immediately after the opening triple backticks. 26 | 27 | In the following sample, we configure JavaScript syntax highlighting for the code block by adding the `js` language identifier. 28 | 29 | ||| :icon-code: Source 30 | ~~~ 31 | ```js 32 | const msg = "hello, world"; 33 | ``` 34 | ~~~ 35 | ||| :icon-play: Demo 36 | ```js 37 | const msg = "hello, world"; 38 | ``` 39 | ||| 40 | 41 | --- 42 | 43 | Retype uses [PrismJS](https://prismjs.com/) for syntax highlighting. All PrismJS language modules are dynamically loaded as required and all Prism [supported languages](https://prismjs.com/#supported-languages) are supported by Retype. 44 | 45 | ## Title 46 | 47 | Retype includes the functionality to set a title on your markdown code blocks. 48 | 49 | +++ :icon-code: Source 50 | ~~~ 51 | ``` Code Block title 52 | const msg = "Set a code block title"; 53 | ``` 54 | ~~~ 55 | +++ :icon-play: Demo 56 | ``` Code Block title 57 | const msg = "Set a code block title"; 58 | ``` 59 | +++ 60 | 61 | The title can be used in conjunction with the code reference type. 62 | 63 | +++ :icon-code: Source 64 | ~~~ 65 | ```js Code Block title 66 | const msg = "Set a code block title"; 67 | ``` 68 | ~~~ 69 | +++ :icon-play: Demo 70 | ```js Code Block title 71 | const msg = "Set a code block title"; 72 | ``` 73 | +++ 74 | 75 | The `title` should be separated from the opening fence by one space, for example the pattern `` ``` Code Block title`` is recommended. 76 | 77 | If a code language is used, separate the `title` from the `lang` by one space. The pattern `` ```js Code Block title`` will work as expected. 78 | 79 | --- 80 | 81 | ## Line highlighting 82 | 83 | Highlight a specific line or range of lines in a code block component using the line highlighting syntax. 84 | 85 | After the opening `` ``` `` of a code block component, add a space and then start your line highlighting configuration with a `#` character. For instance, to highlight the first line, use `` ``` #1 ``. 86 | 87 | Here are a few other common scenarios with additional samples below: 88 | 89 | Scenario | Sample | Description 90 | --- | --- | --- 91 | Single line | `#2` | Highlight line #2 92 | Line range | `#2-5` | Highlight lines #2 to #5 93 | Single line and a range | `#2,4-8` | Highlight line #2 and lines #4 to #8 94 | Multiple line ranges | `#1-2,4-8` | Highlight lines #1 to #2 and lines #4 to #8. 95 | Remove line numbering | `!#4-8` | Remove line numbering and highlight lines #4 to #8 96 | 97 | ### Single line 98 | 99 | Highlight a single line number. 100 | 101 | +++ :icon-code: Source 102 | 103 | ~~~md 104 | ```js #2 105 | {{ include "snippets/simple-code-sample" }} 106 | ``` 107 | ~~~ 108 | 109 | +++ :icon-play: Demo 110 | 111 | ```js #2 112 | {{ include "snippets/simple-code-sample" }} 113 | ``` 114 | 115 | +++ 116 | 117 | ### Line range 118 | 119 | Highlight a range of lines by separating the start and end line number with a `-` dash. 120 | 121 | +++ :icon-code: Source 122 | 123 | ~~~md 124 | ```js #5-7 125 | {{ include "snippets/simple-code-sample" }} 126 | ``` 127 | ~~~ 128 | 129 | +++ :icon-play: Demo 130 | 131 | ```js #5-7 132 | {{ include "snippets/simple-code-sample" }} 133 | ``` 134 | 135 | +++ 136 | 137 | ### Multiple ranges 138 | 139 | Configure multiple line ranges by separating each block with a `,` comma. 140 | 141 | +++ :icon-code: Source 142 | 143 | ~~~md 144 | ```js #2-3,5-7 145 | {{ include "snippets/simple-code-sample" }} 146 | ``` 147 | ~~~ 148 | 149 | +++ :icon-play: Demo 150 | 151 | ```js #2-3,5-7 152 | {{ include "snippets/simple-code-sample" }} 153 | ``` 154 | 155 | +++ 156 | 157 | ### With no line numbers 158 | 159 | Disable the default line numbering but still highlight a line or range of lines. 160 | 161 | +++ :icon-code: Source 162 | 163 | ~~~md 164 | ```js !#2-3,5-7 165 | {{ include "snippets/simple-code-sample" }} 166 | ``` 167 | ~~~ 168 | 169 | +++ :icon-play: Demo 170 | 171 | ```js !#2-3,5-7 172 | {{ include "snippets/simple-code-sample" }} 173 | ``` 174 | 175 | +++ 176 | 177 | ### Using attribute syntax 178 | 179 | Configuring line highlighting using the `highlight` attribute syntax is also supported by Retype. 180 | 181 | +++ :icon-code: Source 182 | 183 | ~~~md 184 | ```js:highlight="2-3,5-7" 185 | {{ include "snippets/simple-code-sample" }} 186 | ``` 187 | ~~~ 188 | 189 | +++ :icon-play: Demo 190 | 191 | ```js:highlight="2-3,5-7" 192 | {{ include "snippets/simple-code-sample" }} 193 | ``` 194 | 195 | +++ 196 | 197 | --- 198 | 199 | ## Line numbers 200 | 201 | Adding or removing line numbering for your code blocks can be configured by adding the `#` specifier character to the first line after the reference language. 202 | 203 | ||| :icon-code: Source 204 | ~~~ 205 | ```js # 206 | const msg = "hello, world"; 207 | ``` 208 | ~~~ 209 | ||| :icon-play: Demo 210 | ```js # 211 | const msg = "hello, world"; 212 | ``` 213 | ||| 214 | 215 | You can also add a title after the `#`: 216 | 217 | +++ :icon-code: Source 218 | 219 | ~~~ 220 | ```js # Your title here 221 | const msg = "hello, world"; 222 | ``` 223 | ~~~ 224 | 225 | +++ :icon-play: Demo 226 | 227 | ```js # Your title here 228 | const msg = "hello, world"; 229 | ``` 230 | 231 | +++ 232 | 233 | The `#` should be separated from the opening `` ``` `` by one space, for example the pattern `` ``` #`` is recommended. 234 | 235 | If a title is added, the title must also be separated from the `#` by one space. For instance, the pattern `` ``` # Your title here`` would work as expected and the pattern `` ``` #Your title here`` would not. 236 | 237 | Line numbering can also be configured at the project level using the [`snippets`](/configuration/project.md#snippets) config on your projects **retype.yml** file. For instance, instructing Retype to add line numbering to all `js` and `json` code blocks across the website would require the following config: 238 | 239 | ```json Enable line numbering for js and json code blocks site wide 240 | { 241 | "snippets": { 242 | "lineNumbers": [ "js", "json" ] 243 | } 244 | } 245 | ``` 246 | 247 | With the above `snippets` config, then you would not have to add the `#` specifier to each code block. All `js` and `json` code blocks would automatically get line numbers. 248 | 249 | ||| Without `snippets` config 250 | ```js # 251 | const msg = "Hello, world"; 252 | ``` 253 | ||| With `snippets` config 254 | ```js 255 | const msg = "Hello, world"; 256 | ``` 257 | ||| 258 | 259 | --- 260 | 261 | ## Disable line numbers 262 | 263 | If you configure a site wide [`snippets`](/configuration/project.md#snippets) for a language and would like to explicitly remove the line numbering for a code block instance of that language, please add the [`!#`](#disable-line-numbers) specifier to the code block instance. 264 | 265 | ||| :icon-code: Source 266 | ~~~ 267 | ```js !# 268 | const msg = "Hello, world"; 269 | ``` 270 | ~~~ 271 | ||| :icon-play: Demo 272 | ```js !# 273 | const msg = "Hello, world"; 274 | ``` 275 | ||| 276 | 277 | --- 278 | 279 | ## Code group 280 | 281 | Code blocks can be grouped using a [[Tab]] component that lets you combine multiple code blocks into a tabbed interface. Each code block becomes a separate tab that users can switch between. 282 | 283 | To create a code group in Retype, simply wrap each code block with `+++` followed by the tab label. The tab label will be displayed as the tab button text. 284 | 285 | Here's an example showing the same "Hello, world" program in different languages: 286 | 287 | +++ :icon-code: JavaScript 288 | ```js 289 | console.log("Hello, world!"); 290 | ``` 291 | +++ :icon-code: TypeScript 292 | ```ts 293 | console.log("Hello, world!"); 294 | ``` 295 | +++ :icon-code: Python 296 | ```py 297 | print('Hello, world!') 298 | +++ --------------------------------------------------------------------------------