Retype v2.0.0-preview now available

[geoffreymcgill]

Version 2.0.0-preview

See comments below.

There were 46 changes in Retype 2.0.0-preview.

New

1. Content templating support with includes, variables, and logic operators. See Variables #213.
2. Page content live editor.
3. Ability to enable/disable templating per page.
4. Support line ranges for partial content.
5. Line highlighting in code blocks. See Codeblock line highlighting #176.
6. Custom <script> or <style> blocks within a page. See Width of the images #255.
7. Google TagManager integration. See Is it possible to add a Google tag? #234.
8. Plausible.io integration. See support plausible.io integration #272.
9. Allow img and alerts above h1 heading.
10. Improved maximum page limit handling.
11. If page level title config and no top level h1, inject the title as the top most element.
12. Magic site-wide includes. See support plausible.io integration #272.
13. Allow generic attributes for Markdown native elements. See Any way to set custom heading ID? #278.
14. New ghost variant for Button, Badge, and Alert components.
15. Include page description in search index and results. See Ability for full content search when no matching headings can be found #59.
16. New search index mode with full, partial, and basic` options.
17. Complete redesign of Search results. See Ability for full content search when no matching headings can be found #59.

Improved

1. Highlight search input query in search results.
2. Improved collapse-on-click for left sidebar folder when there is a default page. See Some octicons break the expand/collapse function #128.
3. Add README to Yarn and NPM package directories.
4. Remove deleted items from output when in memory watch mode.
5. Ability to include .yaml files as resources.
6. Improvement to ToC highlight tracking. See right sidebar highlights wrong current title #41, Incorrect highlighting of inner table of content links #134.
7. Revise wallet path to .retype/license.dat. See Why does Retype create a wallet.dat file? #262.
8. Migrate to .NET 6.
9. Improved link resolution of relative URLs.
10. Slight font-size increase on h1 and h2.
11. Adjustments to layout widths and resize breakpoints. See Specific layout/theme/style suggestions #57.
12. Hide ToC Contents heading if no inner page sub-headings.
13. Upgrade Octicons icons library from v16.1.1 to v17.0.0.

Fixed

1. Unable to scroll sidebar when navigating to a collapsed clickable sidebar menu. See Some octicons break the expand/collapse function #128.
2. Double-quote in image caption is not encoded. See Image caption seems to break page #245.
3. Build fails if root retype.yml configuration file is blank. See Getting error when trying to build retype page with gitpages. #257.
4. Super mega long word in page title causes rendering issue. See Navigation, performance and overflow issues on larger datasets #253.
5. Prevent float elements from interacting with Previous|Next buttons. See Left aligned image at the bottom causes prev & next buttons to jump up #232.
6. Angle brackets are not rendered in the Sidebar.
7. Mustache template syntax is not being escaped.
8. Unreliable sidebar and Prev/Next button label word wrapping. See Navigation, performance and overflow issues on larger datasets #253.
9. Scroll position is not being maintained in retype watch.
10. route not respected if configured on a folder more than one level higher.
11. Full width Alert component content. See Alert component's content should be of full width #242.
12. API Generation of C# Namespaces converts the CamelCase names to all lowercase except the first letter. See API Generation of C# Namespaces converts the CamelCase names to all lowercase except the first letter #277.

Breaking Changes

1. Pages with redirect config to be visible by default in main sidebar navigation. See Link external in Nav #236.

---

This discussion was created from the release v2.0.0-preview.

[geoffreymcgill]

Retype v2.0.0-preview is now available!

The Release notes for v2.0.0-preview are provided above.

We still have a lot of work to do on the documentation and upgrade guides, but you should be able to simply upgrade to v2.0.0-preview if you want to test. Everything should just work and you will now have access to all the new features and improvements in v2.0.0.

The retype.com website is now using the v2.0.0-preview release. The new search results and live-editor (available in retype watch mode only) are my favourite new features.

The content templating functionality is amazing and we will be publishing docs and guides soon. Including a partial file into one of your .md pages would be done using the syntax {{ include "partial.md" }}, where partial.md is the name of the partial file you would like to include.

To install Retype v2.0.0-preview you should first uninstall Retype and then fresh install the preview release.

Step 1. Uninstall

Depending on your platform, use one of the following commands to uninstall Retype:

npm uninstall retypeapp --global
yarn global remove retypeapp
dotnet tool uninstall retypeapp --global

Step 2. Install

npm install [email protected] --global
yarn global install [email protected]
dotnet tool install retypeapp --global --version 2.0.0-preview

If you are using GitHub Pages, your workflow file needs to be updated with the @v2.0.0-preview tag as well. See lines 17 and 21 of the retype.com workflow file as an example:

https://github.com/retypeapp/retype/blob/main/.github/workflows/retype.yml#L17-L21

      - uses: retypeapp/[email protected]

      - uses: retypeapp/[email protected]

After the final release of v2.0.0, you would then need to simplify your workflow again to only @v2.

As mentioned above, we still have an enormous amount of work to do with the docs and announcements. Feel free to ask questions or create new issues and we will do our best to assist.

Please keep in mind, this is a -preview release only. Not the final v2.0.0 release. We will not be adding new features in the final v2.0.0 release, but there may be bug fixes or refinements if issues are discovered with the v2.0.0-preview community testing.

Let us know what you think.

Hope this helps.

[DannyBen]

Shouldn't we already be able to use v2 in GitHub actions?
I am getting an error here.

Installing Retype v2.0.0 using dotnet tool: error.
Error: unable to install retype using the dotnet tool.

And as a side note, I did not expect the version of the action to require change. As far as I can see, the norm is having the action version change when the action itself is different, not when the underlying app is different.

I would consider having the action version fixed from now on, and perhaps support an user input to specify a specific retype version, should they choose to do so.

[geoffreymcgill]

You can remove the following two lines. They are no longer required.

https://github.com/DannyBen/runfile-book/blob/master/.github/workflows/build.yml#L19-L20

        with:
          dotnet-version: 5.0.x

A minimal retype-action.yml would be:

https://retype.com/guides/github-actions/#step-1-add-retype-actionyml-workflow

name: Publish Retype powered website to GitHub Pages
on:
  workflow_dispatch:
  push:
    branches:
      - main

jobs:
  publish:
    name: Publish to retype branch

    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2

      - uses: retypeapp/action-build@v2

      - uses: retypeapp/action-github-pages@v2
        with:
          update-branch: true

[DannyBen]

Thanks. This works, going to deploy all my reytype sites.

[geoffreymcgill]

And as a side note, I did not expect the version of the action to require change. As far as I can see, the norm is having the action version change when the action itself is different, not when the underlying app is different.

I would consider having the action version fixed from now on, and perhaps support an user input to specify a specific retype version, should they choose to do so.

The version number of the retypeapp/action-build and retypeapp/action-github-pages actions track the version number of the main Retype App release. With each new Retype App release, the actions are updated with the same version tags.

We choose to take a conservative and safe approach with the retype-action.yml samples we published. The approach and decision is that the action should use the latest minor release, and not always the latest release. On a Major version upgrade, we wanted users to make a deliberate and manual decision to upgrade. Hence the previous @v1 and now @v2.

PRO TIP: If you want to ALWAYS run with the latest public release, even with a jump in major version, revise the @v2 (or @v1) to @main.

      # - uses: retypeapp/action-build@v2
      - uses: retypeapp/action-build@main

      # - uses: retypeapp/action-github-pages@v2
      - uses: retypeapp/action-github-pages@main

From the very beginning, as a team, we made a strong commitment a decree to not include breaking changes within Retype. We DO NOT want your build process or website breaking between content changes.

That said, if a breaking change must be included, it must only occur on a Major version upgrade (v1.x --> v2.x) and not on a Minor version upgrade (v2.1 --> v2.2).

Since the first line of code, we had a vision for Retype, although it's impossible to foresee all scenarios as the project evolves. With Retype v1, I was not confident we would be able to avoid breaking changes as the project matured into the v2 release.

We made the decision that we wanted developers to choose to upgrade on the major release, at least from v1 to v2.

That decision on whether to still include the @v2 major version tag in our retype-action.yml samples has been reviewed several times, including once again just a couple days ago. I'm feeling quite confident now that we will not have breaking changes and could use the @main tag, but... I was outvoted on that decision. And so, the @v2 stays in the retype-action.yml samples.

We did include one breaking change with the v2 release:

1. Content templating support with includes, variables, and logic operators. See Variables #213.

Personally, I'm not convinced that is actually a breaking change, but we made the decision that it was an important enough of a functionality change that developers were made aware.

I don't see a @v3 major version change happening any time soon. Best I can tell, if it happens, it will likely be years away. If you are confident running on the bleeding edge, use @main tag. If you want to play it safer, keep the @v2 tag.

Hope this helps.

[DannyBen]

Understood, and makes sense.