mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-08 04:51:23 -06:00
Docs: add a migration guide (#1059)
The migration guide is intended to help those using Just the Docs (as a theme or a remote theme) switch from v0.3.3 to v0.4.0. Co-authored-by: Matt Wang <matt@matthewwang.me>
This commit is contained in:
Peter Mosses
GitHub
parent
3de6c589aa
commit
81d7e13277
404
MIGRATION.md
Normal file
404
MIGRATION.md
Normal file
@ -0,0 +1,404 @@
|
||||
---
|
||||
title: Migration and Upgrading
|
||||
layout: default
|
||||
---
|
||||
|
||||
# Migrating and Upgrading
|
||||
|
||||
Summary
|
||||
: A site that uses `just-the-docs` (as a theme or as a remote them) automatically
|
||||
switches to a new release, unless it is pinned to a previous version.
|
||||
|
||||
This migration guide draws attention to:
|
||||
|
||||
- changes that might break your site,
|
||||
- features added in the latest release, and
|
||||
- features that have become deprecated (and are likely to be removed in a future release).
|
||||
|
||||
This document contains instructions on how to migrate and upgrade Just the Docs sites from every minor or major version bump, starting from `v0.3.3` to `v0.4.0`.
|
||||
|
||||
<details open markdown="block">
|
||||
<summary>
|
||||
Table of contents
|
||||
</summary>
|
||||
{: .text-delta }
|
||||
- TOC
|
||||
{:toc}
|
||||
</details>
|
||||
|
||||
{::options toc_levels="2..4" /}
|
||||
|
||||
{: .warning }
|
||||
> If your configuration states `remote_theme: just-the-docs/just-the-docs`, your
|
||||
> website is built using the current `main` branch of the theme, which may include
|
||||
> changes made after the latest release; see the [CHANGELOG].
|
||||
>
|
||||
> If your configuration states `theme: just the docs` and your `Gemfile` specifies
|
||||
> `gem "just-the-docs"`, your website is always built using the latest release.
|
||||
|
||||
{: .note }
|
||||
> If you have cloned/forked and customised the theme repo,
|
||||
> and pull the changes of a new release to your clone,
|
||||
> you may need to resolve merge conflicts.
|
||||
|
||||
[CHANGELOG]: {{ site.baseurl }}{% link CHANGELOG.md %}
|
||||
|
||||
## v0.3.3 … v0.4.x
|
||||
|
||||
### REPOSITORY CHANGES
|
||||
|
||||
#### Just the Docs
|
||||
|
||||
The theme repo is now at <https://github.com/just-the-docs/just-the-docs>.
|
||||
The name of its default branch is now `main`.
|
||||
|
||||
The theme docs website is now published at <https://just-the-docs.github.io/just-the-docs>.
|
||||
|
||||
GitHub provides access to previous versions of the theme repo.
|
||||
You can browse [previous versions of the theme docs website] on the [Internet Archive].
|
||||
|
||||
[previous versions of the theme docs website]: https://web.archive.org/web/20220000000000*/https://just-the-docs.github.io/just-the-docs
|
||||
[Internet Archive]: https://web.archive.org/
|
||||
|
||||
The [README] page on the theme repo repeats much of the information from the [home page],
|
||||
formatted for browsing on GitHub.
|
||||
It also explains how to install the theme as a Ruby Gem, without creating a new site.
|
||||
|
||||
[README]: https://github.com/just-the-docs/just-the-docs/blob/main/README.md
|
||||
[home page]: https://just-the-docs.github.io/just-the-docs
|
||||
|
||||
#### Deploy previews
|
||||
|
||||
When a PR builds successfully, Netlify provides a preview of how the theme docs website will look if the PR is merged.
|
||||
You can find links to the preview near the bottom of the Conversation tab of the PR.
|
||||
|
||||
#### Just the Docs Template
|
||||
|
||||
The template at <https://github.com/just-the-docs/just-the-docs-template>
|
||||
creates a repo with the minimal source files for a Just the Docs website.
|
||||
After configuring the relevant parameters, you can build and serve the website
|
||||
both locally and on GitHub Pages – using either Jekyll 3 or Jekyll 4!
|
||||
|
||||
#### Just the Docs Tests
|
||||
|
||||
The tests website at <https://just-the-docs.github.io/just-the-docs-tests>
|
||||
consists mainly of regression tests for bug fixes and new features.
|
||||
|
||||
The test source files at <https://github.com/just-the-docs/just-the-docs-tests>
|
||||
illustrate the use of many Markdown and Jekyll features,
|
||||
including some that are not included in the theme docs.
|
||||
|
||||
For example, see how to add support for rendering TeX/LaTeX [math formulas] with KaTeX and MathJax.
|
||||
|
||||
[math formulas]: https://just-the-docs.github.io/just-the-docs-tests/components/math/index/
|
||||
|
||||
### POTENTIALLY-BREAKING CHANGES in v0.4.0
|
||||
|
||||
If switching to a new release of the theme breaks your website,
|
||||
check that you don't have any files in the `_includes`, `_layouts`, and `_sass`
|
||||
directories with the same names as files provided by the theme.
|
||||
|
||||
If your repo has a customised copy of `_layouts/default.html` from a previous release,
|
||||
try removing it, or replace it by a fresh copy of the theme file.
|
||||
|
||||
{: .warning }
|
||||
The following changes made in v0.4.0 *might* break or adversely affect your website
|
||||
when you next rebuild it, unless you have pinned it!
|
||||
|
||||
#### New includes and SCSS
|
||||
|
||||
Version 0.4.0 introduces many new `_includes` files. If you already have an existing include with the same name as a new addition, you will need to migrate or update that include. The new files are (relative to the `_includes` folder):
|
||||
|
||||
- `mermaid_config.js`
|
||||
- `nav_footer_custom`
|
||||
- `search_placeholder_custom`
|
||||
- `toc_heading_custom`
|
||||
- the entire `components/` folder:
|
||||
- `aux_nav`, `breadcrumbs`, `children_nav`, `footer`, `header`, `mermaid`, `search_footer`, `search_header`, `sidebar`
|
||||
- the entire `icons/` folder
|
||||
- `code_copy`, `document`, `expand`, `external_link`, `icons`, `link`, `menu`, `search`
|
||||
- the entire `lunr/` folder
|
||||
- `custom-data.json`, `custom-index.js`
|
||||
|
||||
We have removed some code in `_sass/vendor` and added a new file at `_sass/custom/setup.scss`.
|
||||
|
||||
#### favicons
|
||||
|
||||
The file `_includes/favicon.html` is now ignored by the theme.
|
||||
If you're using it, your website's favicon is no longer displayed by browsers.
|
||||
|
||||
To fix: Move the content of `_includes/favicon.html` to `_includes/head_custom.html`.
|
||||
|
||||
#### Custom callout colors
|
||||
|
||||
The file `_sass/custom/custom.scss` is now imported last: _after_ the configuration of callouts.
|
||||
If you've defined custom color variables for callouts in `_sass/custom/custom.scss`
|
||||
(and used them when configuring your callouts in `_config.yml`)
|
||||
you will not be able to rebuild your website.
|
||||
|
||||
To fix: Move custom color variables for callouts in `_sass/custom/custom.scss` to `_sass/custom/variables.scss`.
|
||||
|
||||
#### Pages and collections
|
||||
|
||||
Links to ordinary pages now appear in the navigation on sites that use collections.
|
||||
You might want the navigation of your site to consist entirely of collections.
|
||||
|
||||
To fix: Add the front matter `nav_exclude: true` to pages that the navigation should not display.
|
||||
|
||||
#### Relative URLs
|
||||
|
||||
All generated URLs are now relative.
|
||||
This is a bug fix, and unlikely to break any site.
|
||||
|
||||
Relative links to pages within a website support deployment to different servers.
|
||||
|
||||
#### Navigation order
|
||||
|
||||
The order in which the navigation panel lists pages has been simplified.
|
||||
All pages with `nav_order` values now come before all pages that are ordered by `title`.
|
||||
|
||||
If your website has a group of *sibling* pages where some siblings have `nav_order`
|
||||
string values, and others are ordered by numerical `title` values,
|
||||
the former now come before the latter.
|
||||
|
||||
To fix: Add numerical `nav_order` values to the pages with numerical `title` values.
|
||||
|
||||
### DEPRECATIONS
|
||||
|
||||
{: .warning }
|
||||
The following features are deprecated, and to be removed in a future release.
|
||||
|
||||
#### Jekyll 3
|
||||
|
||||
You can still use Jekyll 3 (3.8.5 or later) to build websites using v0.4.0 of the theme.
|
||||
However, future releases of the theme may require the use of Jekyll 4.
|
||||
|
||||
You can already use Jekyll 4 to build your website *locally*.
|
||||
It should look exactly the same as when built with Jekyll 3.[^Jekyll4]
|
||||
|
||||
[^Jekyll4]:
|
||||
Jekyll 4 depends on more recent versions of other gems than Jekyll 3,
|
||||
and the differences between those versions may affect the files of your built site.
|
||||
|
||||
To use Jekyll 4 when building your website *on GitHub Pages*, you need to run GitHub Actions.
|
||||
The simplest way of setting that up in a new repo is to create the repo using the Just the Docs template.
|
||||
To start running Jekyll 4 to build an existing repo on GitHub Pages,
|
||||
you can create a new repo with the template, then copy its `.github/workflows` directory,
|
||||
and update your repo settings to use Actions.
|
||||
|
||||
#### Footer content configuration
|
||||
|
||||
Currently, if your configuration sets `footer_content` to some text,
|
||||
the theme displays that text at the bottom of the main section of each page.
|
||||
|
||||
The file `_includes/footer_custom.html` provides a more general way of customizing
|
||||
not only the text but also the markup for the page footer area.
|
||||
|
||||
You can replicate the current display of `TEXT` in the footer using the following markup:
|
||||
|
||||
```html
|
||||
<p class="text-small text-grey-dk-100 mb-0">TEXT</p>
|
||||
```
|
||||
|
||||
### THEME WEBSITE CHANGES
|
||||
|
||||
The website now uses *callouts*[^callouts] to draw attention to important information.
|
||||
|
||||
[^callouts]:
|
||||
The theme website configuration defines the callout titles and colors used there.
|
||||
Websites that use the theme have to configure their own callout titles and colors.
|
||||
|
||||
The theme uses [semantic versioning].
|
||||
A normal version number takes the form X.Y.Z,
|
||||
where X is the major version, Y is the minor version, and Z is the patch version.
|
||||
The theme uses version X.Y.Z.rcN for pre-release N of version X.Y.Z.
|
||||
When referring to version numbers on GitHub, we usually prefix them by 'v'.
|
||||
|
||||
[semantic versioning]: https://semver.org
|
||||
|
||||
Major version zero (0.Y.Z) is for initial development, where anything *may* change at any time.
|
||||
In practice, we increment the patch version Z for bug fixes and backwards compatible changes;
|
||||
we increment the minor version Y for changes that could break websites using the theme
|
||||
without pinning it to a specific version.
|
||||
|
||||
The label `NEW` in the theme website indicates a feature that has been changed or added
|
||||
since the release of the previous *minor* version.
|
||||
For example, after the release of v0.4.Z, the theme website should label `NEW` all features that
|
||||
we have changed or added since v0.3.0 – not just since v0.3.3.
|
||||
When we release v0.5.0, we will remove all those labels, and add labels on features since v0.4.0.
|
||||
|
||||
The theme docs website is not itself versioned.
|
||||
It changes incrementally, independently of theme releases.
|
||||
|
||||
#### Home page
|
||||
|
||||
The theme home page now focuses on the simplest ways of using the theme.
|
||||
It also notes the different behaviour of `theme` and `remote_theme` in connection
|
||||
with interim versions of the theme, such as pre-releases.
|
||||
|
||||
#### CHANGELOG
|
||||
|
||||
The CHANGELOG page lists the changes made in all previous releases and pre-releases of new versions of the theme gem.
|
||||
|
||||
It also lists changes made to the `main` branch of the theme since the latest release or pre-release.
|
||||
|
||||
For changes since v0.3.3, the log usually references the merged PR that made the change and its author.
|
||||
|
||||
### NON-BREAKING CHANGES (OUTLINE ONLY)
|
||||
|
||||
Brief descriptions of the following changes are to be added below.
|
||||
|
||||
#### Accessibility
|
||||
|
||||
- Skip to main content: the first keyboard-navigatable item is now a link to skip over the sidebar and header to the main content of the page. PR: [#949].
|
||||
- Aria-labels: improved `aria-label`s have been added to various site elements. PRs: [#950], ...
|
||||
- Other general improvements: gradual changes have improved tab focusability, contrast, and semantic elements. More work still to come. PRs: [#498], [#846]
|
||||
|
||||
#### Configuration
|
||||
|
||||
- Mermaid support: first-class support for [Mermaid](https://mermaid.js.org/) - a JavaScript-based diagram and charting tool supported by GitHub - has been added to the theme. **This feature is opt-in.** See the new doc subsections in [Configuration]({% link docs/configuration.md %}#mermaid-diagrams) and [Code]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more.
|
||||
- Multiple Google Analytics tags are now supported. PR: [#1029]
|
||||
|
||||
#### Customization
|
||||
|
||||
- all user-facing text is now customizable; previously, several elements (ex search placeholder) were hardwired into the theme. Now, users can blend custom includes and layouts to internationalize their sites.
|
||||
- we've clarified the role of `custom.scss` to be imported last; to allow users to define custom or override variables, we've added a new file `setup.scss`. PR: [#1135]
|
||||
|
||||
#### Custom Includes
|
||||
|
||||
We've added several custom `_includes` to provide users with more customization options for different site elements. We've also added a section to [Configuration]({% link docs/customization.md %}#override-includes) to outline these.
|
||||
|
||||
All of these are opt-in by default; however, **these may be breaking if you have existing `_includes` with the same name**.
|
||||
|
||||
Each item is listed with the relevant file and PR.
|
||||
|
||||
- TOC heading: `toc_heading_custom.html`, PR: [#980]
|
||||
- Navigation panel footer: `nav_footer_custom.html`, PR: [#474]
|
||||
- Search placeholder: `search_placeholder_custom.html`, PR: [#613]
|
||||
- Modular site components: `components/` and `icons/`, PR: [#1058]
|
||||
- Custom search indices: `lunr/`, PR: [#1068]
|
||||
|
||||
In a future (version 1) release, we may rename the custom include files.
|
||||
|
||||
#### Modular Components
|
||||
|
||||
We've broken up the default layout (`_layouts/default.html`) into multiple reusable components. This should have no impact on most users; however, it should make it easier to implement custom layouts.
|
||||
|
||||
For more, see [Custom layouts and includes]({% link docs/customization.md %}#custom-layouts-and-includes). PR: [#1058].
|
||||
|
||||
#### Navigation
|
||||
|
||||
- Collections: nav panel shows links to ordinary pages before collections
|
||||
- Collection folding; part of "Combination". PR: [#578]
|
||||
- Scrolling to show link to selected page. PR: [#639]
|
||||
- External nav links are now supported. PR: [#876]
|
||||
- Child nav order: sort navigation pages with `child_nav_order`. PR: [#726]
|
||||
- Order when mixing different ways of specifying nav order
|
||||
|
||||
#### Search
|
||||
|
||||
In addition to customizing the search placeholder, we've also added the ability to provide custom content to the search index. for more, see [Custom content for search index]({% link docs/search.md %}#custom-content-for-search-index). PR: [#1068].
|
||||
|
||||
#### Styling
|
||||
|
||||
- Code copying: code blocks now allow users to easily copy their contents. PR: [#945]
|
||||
- Blockquote: shows vertical bar on left. PR: [#965]
|
||||
- Links wrap. PR: [#905]
|
||||
- Callouts: a new component similar to alerts or banners. See [UI Components - Callouts]({% link docs/ui-components/callouts.md %}). PR: [#466]
|
||||
|
||||
----
|
||||
|
||||
[#856]: https://github.com/just-the-docs/just-the-docs/pull/856
|
||||
[#806]: https://github.com/just-the-docs/just-the-docs/pull/806
|
||||
[#555]: https://github.com/just-the-docs/just-the-docs/pull/555
|
||||
[#814]: https://github.com/just-the-docs/just-the-docs/pull/814
|
||||
[#778]: https://github.com/just-the-docs/just-the-docs/pull/778
|
||||
[#221]: https://github.com/just-the-docs/just-the-docs/pull/221
|
||||
[#782]: https://github.com/just-the-docs/just-the-docs/pull/782
|
||||
[#549]: https://github.com/just-the-docs/just-the-docs/pull/549
|
||||
[#554]: https://github.com/just-the-docs/just-the-docs/pull/554
|
||||
[#499]: https://github.com/just-the-docs/just-the-docs/pull/499
|
||||
[#473]: https://github.com/just-the-docs/just-the-docs/pull/473
|
||||
[#835]: https://github.com/just-the-docs/just-the-docs/pull/835
|
||||
[#891]: https://github.com/just-the-docs/just-the-docs/pull/891
|
||||
[#906]: https://github.com/just-the-docs/just-the-docs/pull/906
|
||||
|
||||
[#578]: https://github.com/just-the-docs/just-the-docs/pull/578
|
||||
[#463]: https://github.com/just-the-docs/just-the-docs/pull/463
|
||||
[#448]: https://github.com/just-the-docs/just-the-docs/pull/448
|
||||
[#466]: https://github.com/just-the-docs/just-the-docs/pull/466
|
||||
[#477]: https://github.com/just-the-docs/just-the-docs/pull/477
|
||||
[#495]: https://github.com/just-the-docs/just-the-docs/pull/495
|
||||
[#496]: https://github.com/just-the-docs/just-the-docs/pull/496
|
||||
[#498]: https://github.com/just-the-docs/just-the-docs/pull/498
|
||||
[#494]: https://github.com/just-the-docs/just-the-docs/pull/494
|
||||
[#639]: https://github.com/just-the-docs/just-the-docs/pull/639
|
||||
[#544]: https://github.com/just-the-docs/just-the-docs/pull/544
|
||||
[#364]: https://github.com/just-the-docs/just-the-docs/pull/364
|
||||
[#498]: https://github.com/just-the-docs/just-the-docs/pull/498
|
||||
[#613]: https://github.com/just-the-docs/just-the-docs/pull/613
|
||||
[#726]: https://github.com/just-the-docs/just-the-docs/pull/726
|
||||
[#474]: https://github.com/just-the-docs/just-the-docs/pull/474
|
||||
[#829]: https://github.com/just-the-docs/just-the-docs/pull/829
|
||||
[#857]: https://github.com/just-the-docs/just-the-docs/pull/857
|
||||
[#876]: https://github.com/just-the-docs/just-the-docs/pull/876
|
||||
[#909]: https://github.com/just-the-docs/just-the-docs/pull/909
|
||||
[#519]: https://github.com/just-the-docs/just-the-docs/pull/519
|
||||
[#855]: https://github.com/just-the-docs/just-the-docs/pull/855
|
||||
[#686]: https://github.com/just-the-docs/just-the-docs/pull/686
|
||||
[#495]: https://github.com/just-the-docs/just-the-docs/pull/495
|
||||
[#846]: https://github.com/just-the-docs/just-the-docs/pull/846
|
||||
[#727]: https://github.com/just-the-docs/just-the-docs/pull/727
|
||||
[#889]: https://github.com/just-the-docs/just-the-docs/pull/889
|
||||
[#893]: https://github.com/just-the-docs/just-the-docs/pull/893
|
||||
[#905]: https://github.com/just-the-docs/just-the-docs/pull/905
|
||||
[#898]: https://github.com/just-the-docs/just-the-docs/pull/898
|
||||
|
||||
[#950]: https://github.com/just-the-docs/just-the-docs/pull/950
|
||||
[#944]: https://github.com/just-the-docs/just-the-docs/pull/944
|
||||
[#939]: https://github.com/just-the-docs/just-the-docs/pull/939
|
||||
[#949]: https://github.com/just-the-docs/just-the-docs/pull/949
|
||||
[#941]: https://github.com/just-the-docs/just-the-docs/pull/941
|
||||
[#956]: https://github.com/just-the-docs/just-the-docs/pull/956
|
||||
[#935]: https://github.com/just-the-docs/just-the-docs/pull/935
|
||||
[#940]: https://github.com/just-the-docs/just-the-docs/pull/940
|
||||
[#951]: https://github.com/just-the-docs/just-the-docs/pull/951
|
||||
[#955]: https://github.com/just-the-docs/just-the-docs/pull/955
|
||||
[#937]: https://github.com/just-the-docs/just-the-docs/pull/937
|
||||
|
||||
[#965]: https://github.com/just-the-docs/just-the-docs/pull/965
|
||||
[#960]: https://github.com/just-the-docs/just-the-docs/pull/960
|
||||
[#962]: https://github.com/just-the-docs/just-the-docs/pull/962
|
||||
[#964]: https://github.com/just-the-docs/just-the-docs/pull/964
|
||||
[#967]: https://github.com/just-the-docs/just-the-docs/pull/967
|
||||
[#974]: https://github.com/just-the-docs/just-the-docs/pull/974
|
||||
[#980]: https://github.com/just-the-docs/just-the-docs/pull/980
|
||||
[#985]: https://github.com/just-the-docs/just-the-docs/pull/985
|
||||
[#986]: https://github.com/just-the-docs/just-the-docs/pull/986
|
||||
[#992]: https://github.com/just-the-docs/just-the-docs/pull/992
|
||||
|
||||
[#945]: https://github.com/just-the-docs/just-the-docs/pull/945
|
||||
[#999]: https://github.com/just-the-docs/just-the-docs/pull/999
|
||||
[#1000]: https://github.com/just-the-docs/just-the-docs/pull/1000
|
||||
[#1001]: https://github.com/just-the-docs/just-the-docs/pull/1001
|
||||
[#1010]: https://github.com/just-the-docs/just-the-docs/pull/1010
|
||||
[#1015]: https://github.com/just-the-docs/just-the-docs/pull/1015
|
||||
[#1018]: https://github.com/just-the-docs/just-the-docs/pull/1018
|
||||
[#1019]: https://github.com/just-the-docs/just-the-docs/pull/1019
|
||||
[#1021]: https://github.com/just-the-docs/just-the-docs/pull/1021
|
||||
[#1027]: https://github.com/just-the-docs/just-the-docs/pull/1027
|
||||
[#1029]: https://github.com/just-the-docs/just-the-docs/pull/1029
|
||||
[#1040]: https://github.com/just-the-docs/just-the-docs/pull/1040
|
||||
[#1061]: https://github.com/just-the-docs/just-the-docs/pull/1061
|
||||
[#1065]: https://github.com/just-the-docs/just-the-docs/pull/1065
|
||||
[#1071]: https://github.com/just-the-docs/just-the-docs/pull/1071
|
||||
[#1074]: https://github.com/just-the-docs/just-the-docs/pull/1074
|
||||
[#1076]: https://github.com/just-the-docs/just-the-docs/pull/1076
|
||||
[#1077]: https://github.com/just-the-docs/just-the-docs/pull/1077
|
||||
[#1090]: https://github.com/just-the-docs/just-the-docs/pull/1090
|
||||
[#1091]: https://github.com/just-the-docs/just-the-docs/pull/1091
|
||||
[#1092]: https://github.com/just-the-docs/just-the-docs/pull/1092
|
||||
[#1095]: https://github.com/just-the-docs/just-the-docs/pull/1095
|
||||
|
||||
[#1068]: https://github.com/just-the-docs/just-the-docs/pull/1068
|
||||
[#1135]: https://github.com/just-the-docs/just-the-docs/pull/1135
|
||||
Loading…
x
Reference in New Issue
Block a user