Skip to content
Snippets Groups Projects
Commit a3b1d1ff authored by Bernd Taschler's avatar Bernd Taschler
Browse files

Merge branch 'migrate-jtd' into 'master' 

Clean up old files from JTD fork.

Closes #66

See merge request !27
parents bab51830 d944c78a
No related branches found
No related tags found
1 merge request!27Clean up old files from JTD fork.
Pipeline #26808 passed
Stage: test
Stage: deploy
Expand all Hide whitespace changes
Inline Side-by-side
Showing
with 0 additions and 3460 deletions
.devcontainer/Dockerfile deleted 100644 → 0
+ 0
− 14
View file @ bab51830
# [Choice] Debian OS version (use bullseye on local arm64/Apple Silicon): bullseye, buster
ARG VARIANT=bullseye
FROM mcr.microsoft.com/vscode/devcontainers/jekyll:0-${VARIANT}
# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
ARG NODE_VERSION="none"
RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
# && apt-get -y install --no-install-recommends <your-package-list-here>
# [Optional] Uncomment this line to install global node packages.
# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1
\ No newline at end of file
.devcontainer/base.Dockerfile deleted 100644 → 0
+ 0
− 26
View file @ bab51830
# [Choice] Debian OS version (use 2.7-bullseye on local arm64/Apple Silicon): 2.7-bullseye, 2.7-buster
ARG VARIANT=2.7-bullseye
FROM mcr.microsoft.com/vscode/devcontainers/ruby:${VARIANT}
COPY library-scripts/meta.env /usr/local/etc/vscode-dev-containers
# ENV Variables required by Jekyll
ENV LANG=en_US.UTF-8 \
LANGUAGE=en_US:en \
TZ=Etc/UTC \
LC_ALL=en_US.UTF-8 \
LANG=en_US.UTF-8 \
LANGUAGE=en_US
# Install bundler, latest jekyll, and github-pages for older jekyll
RUN gem install bundler jekyll github-pages
# [Choice] Node.js version: none, lts/*, 16, 14, 12, 10
ARG NODE_VERSION="none"
RUN if [ "${NODE_VERSION}" != "none" ]; then su vscode -c "umask 0002 && . /usr/local/share/nvm/nvm.sh && nvm install ${NODE_VERSION} 2>&1"; fi
# [Optional] Uncomment this section to install additional OS packages.
# RUN apt-get update && export DEBIAN_FRONTEND=noninteractive \
# && apt-get -y install --no-install-recommends <your-package-list-here>
# [Optional] Uncomment this line to install global node packages.
# RUN su vscode -c "source /usr/local/share/nvm/nvm.sh && npm install -g <your-package-here>" 2>&1
.devcontainer/devcontainer.json deleted 100644 → 0
+ 0
− 35
View file @ bab51830
// For format details, see https://aka.ms/devcontainer.json. For config options, see the README at:
// https://github.com/microsoft/vscode-dev-containers/tree/v0.224.2/containers/jekyll
{
"name": "Just the docs",
"build": {
"dockerfile": "Dockerfile",
"args": {
// Update 'VARIANT' to pick a Debian OS version: bullseye, buster
// Use bullseye when on local arm64/Apple Silicon.
"VARIANT": "bullseye",
// Enable Node.js: pick the latest LTS version
"NODE_VERSION": "lts/*"
}
},
// Set *default* container specific settings.json values on container create.
"settings": {},
// Add the IDs of extensions you want installed when the container is created.
"extensions": ["GitHub.vscode-pull-request-github"],
// Use 'forwardPorts' to make a list of ports inside the container available locally.
"forwardPorts": [
// Jekyll server
4000,
// Live reload server
35729
],
// Use 'postCreateCommand' to run commands after the container is created.
"postCreateCommand": "sh .devcontainer/post-create.sh",
// Comment out to connect as root instead. More info: https://aka.ms/vscode-remote/containers/non-root.
"remoteUser": "vscode"
}
.devcontainer/post-create.sh deleted 100644 → 0
+ 0
− 12
View file @ bab51830
#!/bin/sh
# Install the version of Bundler.
if [ -f Gemfile.lock ] && grep "BUNDLED WITH" Gemfile.lock > /dev/null; then
cat Gemfile.lock | tail -n 2 | grep -C2 "BUNDLED WITH" | tail -n 1 | xargs gem install bundler -v
fi
# If there's a Gemfile, then run `bundle install`
# It's assumed that the Gemfile will install Jekyll too
if [ -f Gemfile ]; then
bundle install
fi
.prettierignore deleted 100644 → 0
+ 0
− 10
View file @ bab51830
package.json
package-lock.json
_site
assets/css/just-the-docs-default.scss
assets/css/just-the-docs-light.scss
assets/css/just-the-docs-dark.scss
assets/js/vendor/lunr.min.js
assets/js/search-data.json
assets/js/just-the-docs.js
*.md
.prettierrc deleted 100644 → 0
+ 0
− 7
View file @ bab51830
{
"endOfLine": "lf",
"semi": false,
"singleQuote": false,
"tabWidth": 2,
"trailingComma": "es5"
}
\ No newline at end of file
.stylelintrc.json deleted 100644 → 0
+ 0
− 20
View file @ bab51830
{
"ignoreFiles": [
"assets/css/just-the-docs-default.scss",
"assets/css/just-the-docs-light.scss",
"assets/css/just-the-docs-dark.scss",
"_sass/vendor/**/*.scss"
],
"extends": [
"stylelint-config-standard-scss",
"stylelint-config-prettier-scss"
],
"plugins": ["stylelint-prettier"],
"rules": {
"prettier/prettier": true,
"alpha-value-notation": null,
"color-function-notation": null,
"no-descending-specificity": null,
"scss/no-global-function-names": null
}
}
.vscode/tasks.json deleted 100644 → 0
+ 0
− 26
View file @ bab51830
{
// See https://go.microsoft.com/fwlink/?LinkId=733558
// for the documentation about the tasks.json format
"version": "2.0.0",
"tasks": [
{
"label": "Serve",
"type": "shell",
"command": "bundle exec jekyll serve --livereload",
"group": {
"kind": "test",
"isDefault": true
},
"isBackground": true
},
{
"label": "Build",
"type": "shell",
"command": "bundle exec jekyll build",
"group": {
"kind": "build",
"isDefault": true
}
}
]
}
CHANGELOG.md deleted 100644 → 0
+ 0
− 1239
View file @ bab51830
This diff is collapsed.
Dockerfile deleted 100644 → 0
+ 0
− 12
View file @ bab51830
FROM ruby:2.7
ENV LC_ALL C.UTF-8
ENV LANG en_US.UTF-8
ENV LANGUAGE en_US.UTF-8
WORKDIR /usr/src/app
COPY Gemfile just-the-docs.gemspec ./
RUN gem install bundler && bundle install
EXPOSE 4000
MIGRATION.md deleted 100644 → 0
+ 0
− 403
View file @ bab51830
---
title: Migration and Upgrading
layout: default
nav_exclude: true
---
# 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)
#### 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
docker-compose.yml deleted 100644 → 0
+ 0
− 14
View file @ bab51830
version: "3.5"
services:
jekyll:
build:
context: ./
ports:
- 4000:4000
volumes:
- .:/usr/src/app
stdin_open: true
tty: true
command: bundle exec jekyll serve -H 0.0.0.0 -t
docs/configuration.md deleted 100644 → 0
+ 0
− 321
View file @ bab51830
---
layout: default
title: Configuration
nav_order: 2
nav_exclude: true
---
# Configuration
{: .no_toc }
Just the Docs has some specific configuration parameters that can be defined in your Jekyll site's \_config.yml file.
{: .fs-6 .fw-300 }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
View this site's [\_config.yml](https://github.com/just-the-docs/just-the-docs/tree/main/_config.yml) file as an example.
## Site logo
```yaml
# Set a path/url to a logo that will be displayed instead of the title
logo: "/assets/images/just-the-docs.png"
```
## Site favicon
```yaml
# Set a path/url to a favicon that will be displayed by the browser
favicon_ico: "/assets/images/favicon.ico"
```
If the path to your favicon is `/favicon.ico`, you can leave `favicon_ico` unset.
## Search
```yaml
# Enable or disable the site search
# Supports true (default) or false
search_enabled: true
search:
# Split pages into sections that can be searched individually
# Supports 1 - 6, default: 2
heading_level: 2
# Maximum amount of previews per search result
# Default: 3
previews: 3
# Maximum amount of words to display before a matched word in the preview
# Default: 5
preview_words_before: 5
# Maximum amount of words to display after a matched word in the preview
# Default: 10
preview_words_after: 10
# Set the search token separator
# Default: /[\s\-/]+/
# Example: enable support for hyphenated search words
tokenizer_separator: /[\s/]+/
# Display the relative url in search results
# Supports true (default) or false
rel_url: true
# Enable or disable the search button that appears in the bottom right corner of every page
# Supports true or false (default)
button: false
```
## Mermaid Diagrams
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
The minimum configuration requires the key for `version` ([from jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)) in `_config.yml`:
```yaml
mermaid:
# Version of mermaid library
# Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
version: "9.1.3"
```
Provide a `path` instead of a `version` key to load the mermaid library from a local file.
See [the Code documentation]({% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more configuration options and information.
## Aux links
```yaml
# Aux links for the upper right navigation
aux_links:
"Just the Docs on GitHub":
- "//github.com/just-the-docs/just-the-docs"
# Makes Aux links open in a new tab. Default is false
aux_links_new_tab: false
```
## Heading anchor links
```yaml
# Heading anchor links appear on hover over h1-h6 tags in page content
# allowing users to deep link to a particular heading on a page.
#
# Supports true (default) or false
heading_anchors: true
```
## External navigation links
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
External links can be added to the navigation through the `nav_external_links` option.
See [Navigation Structure]({% link docs/navigation-structure.md %}#external-navigation-links) for more details.
## Footer content
```yaml
# Footer content
# appears at the bottom of every page's main content
# Note: The footer_content option is deprecated and will be removed in a future major release. Please use `_includes/footer_custom.html` for more robust
markup / liquid-based content.
footer_content: "Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt\">MIT license.</a>"
# Footer last edited timestamp
last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
# Footer "Edit this page on GitHub" link text
gh_edit_link: true # show or hide edit this page link
gh_edit_link_text: "Edit this page on GitHub."
gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo
gh_edit_branch: "main" # the branch that your docs is served from
# gh_edit_source: docs # the source that your files originate from
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
```
_note: `footer_content` is deprecated, but still supported. For a better experience we have moved this into an include called `_includes/footer_custom.html` which will allow for robust markup / liquid-based content._
- the "page last modified" data will only display if a page has a key called `last_modified_date`, formatted in some readable date format
- `last_edit_time_format` uses Ruby's DateTime formatter; see examples and more information [at this link.](https://apidock.com/ruby/DateTime/strftime)
- `gh_edit_repository` is the URL of the project's GitHub repository
- `gh_edit_branch` is the branch that the docs site is served from; defaults to `main`
- `gh_edit_source` is the source directory that your project files are stored in (should be the same as [site.source](https://jekyllrb.com/docs/configuration/options/))
- `gh_edit_view_mode` is `"tree"` by default, which brings the user to the github page; switch to `"edit"` to bring the user directly into editing mode
## Color scheme
```yaml
# Color scheme supports "light" (default) and "dark"
color_scheme: dark
```
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
<script>
const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
jtd.addEvent(toggleDarkMode, 'click', function(){
if (jtd.getTheme() === 'dark') {
jtd.setTheme('light');
toggleDarkMode.textContent = 'Preview dark color scheme';
} else {
jtd.setTheme('dark');
toggleDarkMode.textContent = 'Return to the light side';
}
});
</script>
See [Customization]({% link docs/customization.md %}) for more information.
## Callouts
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
To use this feature, you need to configure a `color` and (optionally) `title` for each kind of callout you want to use, e.g.:
```yaml
callouts:
warning:
title: Warning
color: red
```
This uses the color `$red-000` for the background of the callout, and `$red-300` for the title and box decoration.[^dark] You can then style a paragraph as a `warning` callout like this:
```markdown
{: .warning }
A paragraph...
```
[^dark]:
If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title.
The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/setup.scss` file:
```scss
$pink-000: #f77ef1;
$pink-100: #f967f1;
$pink-200: #e94ee1;
$pink-300: #dd2cd4;
```
You can override the default `opacity` of the background for a particular callout, e.g.:
```yaml
callouts:
custom:
color: pink
opacity: 0.3
```
You can change the default opacity (`0.2`) for all callouts, e.g.:
```yaml
callouts_opacity: 0.3
```
You can also adjust the overall level of callouts.
The value of `callouts_level` is either `quiet` or `loud`;
`loud` increases the saturation and lightness of the backgrounds.
The default level is `quiet` when using the `light` or custom color schemes,
and `loud` when using the `dark color scheme.`
See [Callouts]({% link docs/ui-components/callouts.md %}) for more information.
## Google Analytics
{: .warning }
> [Google Analytics 4 will replace Universal Analytics](https://support.google.com/analytics/answer/11583528). On **July 1, 2023**, standard Universal Analytics properties will stop processing new hits. The earlier you migrate, the more historical data and insights you will have in Google Analytics 4.
Universal Analytics (UA) and Google Analytics 4 (GA4) properties are supported.
```yaml
# Google Analytics Tracking (optional)
# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
ga_tracking: UA-2709176-10
ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
```
### Multiple IDs
{: .d-inline-block .no_toc }
New (v0.4.0)
{: .label .label-green }
This theme supports multiple comma-separated tracking IDs. This helps seamlessly transition UA properties to GA4 properties by tracking both for a while.
```yaml
ga_tracking: "UA-1234567-89,G-1AB234CDE5"
```
## Document collections
By default, the navigation and search include normal [pages](https://jekyllrb.com/docs/pages/).
You can also use [Jekyll collections](https://jekyllrb.com/docs/collections/) which group documents semantically together.
{: .warning }
> Collection folders always start with an underscore (`_`), e.g. `_tests`. You won't see your collections if you omit the prefix.
For example, put all your test files in the `_tests` folder and create the `tests` collection:
```yaml
# Define Jekyll collections
collections:
# Define a collection named "tests", its documents reside in the "_tests" directory
tests:
permalink: "/:collection/:path/"
output: true
just_the_docs:
# Define which collections are used in just-the-docs
collections:
# Reference the "tests" collection
tests:
# Give the collection a name
name: Tests
# Exclude the collection from the navigation
# Supports true or false (default)
# nav_exclude: true
# Fold the collection in the navigation
# Supports true or false (default)
# nav_fold: true # note: this option is new in v0.4
# Exclude the collection from the search
# Supports true or false (default)
# search_exclude: true
```
The navigation for all your normal pages (if any) is displayed before those in collections.
You can reference multiple collections.
This creates categories in the navigation with the configured names.
```yaml
collections:
tests:
permalink: "/:collection/:path/"
output: true
tutorials:
permalink: "/:collection/:path/"
output: true
just_the_docs:
collections:
tests:
name: Tests
tutorials:
name: Tutorials
```
When *all* your pages are in a single collection, its name is not displayed.
The navigation for each collection is a separate name space for page titles: a page in one collection cannot be a child of a page in a different collection, or of a normal page.
docs/customization.md deleted 100644 → 0
+ 0
− 398
View file @ bab51830
---
layout: default
title: Customization
nav_order: 6
nav_exclude: true
---
# Customization
{: .no_toc }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
## Color schemes
Just the Docs supports two color schemes: light (default), and dark.
To enable a color scheme, set the `color_scheme` parameter in your site's `_config.yml` file:
#### Example
{: .no_toc }
```yaml
# Color scheme supports "light" (default) and "dark"
color_scheme: dark
```
<button class="btn js-toggle-dark-mode">Preview dark color scheme</button>
<script>
const toggleDarkMode = document.querySelector('.js-toggle-dark-mode');
jtd.addEvent(toggleDarkMode, 'click', function(){
if (jtd.getTheme() === 'dark') {
jtd.setTheme('light');
toggleDarkMode.textContent = 'Preview dark color scheme';
} else {
jtd.setTheme('dark');
toggleDarkMode.textContent = 'Return to the light side';
}
});
</script>
## Custom schemes
### Define a custom scheme
You can add custom schemes.
If you want to add a scheme named `foo` (can be any name) just add a file `_sass/color_schemes/foo.scss` (replace `foo` by your scheme name)
where you override theme variables to change colors, fonts, spacing, etc.
{: .note }
Since the default color scheme is `light`, your custom scheme is implicitly based on the variable settings used by the `light` scheme.
If you want your custom scheme to be based on the `dark` scheme, you need to start your file with the following line:
```scss
@import "./color_schemes/dark";
```
You can define custom schemes based on other custom schemes in the same way.
Available variables are listed in the [\_variables.scss](https://github.com/just-the-docs/just-the-docs/tree/main/_sass/support/_variables.scss) file.
For example, to change the link color from the purple default to blue, include the following inside your scheme file:
#### Example
{: .no_toc }
```scss
$link-color: $blue-000;
```
Keep in mind that changing a variable will not automatically change the value of other variables that depend on it.
For example, the default link color (`$link-color`) is set to `$purple-000`. However, redefining `$purple-000` in a custom color scheme will not automatically change `$link-color` to match it.
Instead, each variable that relies on previously-cascaded values must be manually reimplemented by copying the dependent rules from `_variables.scss` — in this case, rewriting `$link-color: $purple-000;`.
_Note:_ Editing the variables directly in `_sass/support/variables.scss` is not recommended and can cause other dependencies to fail.
Please use scheme files.
### Use a custom scheme
To use the custom color scheme, only set the `color_scheme` parameter in your site's `_config.yml` file:
```yaml
color_scheme: foo
```
### Switchable custom scheme
If you want to be able to change the scheme dynamically, for example via javascript, just add a file `assets/css/just-the-docs-foo.scss` (replace `foo` by your scheme name)
with the following content:
{% raw %}
---
---
{% include css/just-the-docs.scss.liquid color_scheme="foo" %}
{% endraw %}
This allows you to switch the scheme via the following javascript.
```js
jtd.setTheme("foo")
```
## Override and define new variables
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
To define new SCSS variables, functions, or override existing theme variables, place SCSS code in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section).
This is most commonly-used to define [custom callout colors]({% link docs/configuration.md %}#callouts). For example,
```scss
// _sass/custom/setup.scss
$pink-000: #f77ef1;
$pink-100: #f967f1;
$pink-200: #e94ee1;
$pink-300: #dd2cd4;
```
In particular: this file is imported *after* the theme's variables and functions are defined, but *before* any CSS classes are emitted.
## Override and completely custom styles
For styles that aren't defined as SCSS variables, you may want to modify specific CSS classes.
Additionally, you may want to add completely custom CSS specific to your content.
To do this, put your styles in the file `_sass/custom/custom.scss`.
This will allow for all overrides to be kept in a single file, and for any upstream changes to still be applied.
For example, if you'd like to add your own styles for printing a page, you could add the following styles.
#### Example
{: .no_toc }
```scss
// Print-only styles.
@media print {
.side-bar,
.page-header {
display: none;
}
.main-content {
max-width: auto;
margin: 1em;
}
}
```
## Override includes
You can customize the theme by overriding any of the custom [Jekyll includes](https://jekyllrb.com/docs/includes/) files that it provides.
To do this, create an `_includes` directory and make a copy of the specific file you wish to modify. The content in this file will override the theme defaults. You can learn more about this process in the Jekyll docs for [Overriding theme defaults](https://jekyllrb.com/docs/themes/#overriding-theme-defaults).
Just the Docs provides the following custom includes files:
### Custom TOC Heading
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
`_includes/toc_heading_custom.html`
If the page has any child pages, and `has_toc` is not set to `false`, this content appears as a heading above the [auto-generating list of child pages]({% link docs/navigation-structure.md %}#auto-generating-table-of-contents) after the page's content.
#### Example
{: .no_toc }
To change the default TOC heading to "Contents", create `_includes/toc_heading_custom.html` and add:
```html
<h2 class="text-delta">Contents</h2>
```
The (optional) `text-delta` class makes the heading appear as **Contents**{:.text-delta} .
### Custom Footer
`_includes/footer_custom.html`
This content appears at the bottom of every page's main content. More info for this include can be found in the [Configuration - Footer content]({% link docs/configuration.md %}#footer-content).
### Custom Head
`_includes/head_custom.html`
Any HTML added to this file will be inserted before the closing `<head>` tag. This might include additional `<meta>`, `<link>`, or `<script>` tags.
The `<head>` tag automatically includes a link to an existing favicon if you set `favicon_ico` to the corresponding path in your configuration, or if the path to the favicon is `/favicon.ico`.
### Custom Header
`_includes/header_custom.html`
Content added to this file appears at the top of every page's main content between the site search and auxiliary links if they are enabled. If `search_enabled` were set to false and `aux_links` were removed, the content of `header_custom.html` would occupy the space at the top of every page.
### Custom Nav Footer
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
`_includes/nav_footer_custom.html`
Any content added to this file will appear at the bottom left of the page below the site's navigation. By default an attribution to Just the Docs is displayed which reads, `This site uses Just the Docs, a documentation theme for Jekyll.`.
### Custom Search Placeholder
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
`_includes/search_placeholder_custom.html`
Content added to this file will replace the default placeholder text in the search bar (and its `aria-label`), after stripping HTML and leading/trailing whitespace. By default, the content of the include is:
{% raw %}
```liquid
Search {{site.title}}
```
{% endraw %}
Override this file to render a custom placeholder. One common use-case is internationalization; for example,
{% raw %}
```liquid
Chercher notre site
```
{% endraw %}
would make the placeholder text "Chercher notre site". [Liquid code](https://jekyllrb.com/docs/liquid/) (including [Jekyll variables](https://jekyllrb.com/docs/variables/)) is also supported.
## Custom layouts and includes
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
Advanced
{: .label .label-yellow }
Just the Docs uses Jekyll's powerful [layouts](https://jekyllrb.com/docs/layouts/) and [includes](https://jekyllrb.com/docs/includes/) features to generate and compose various elements of the site. Jekyll users and developers can extend or replace existing layouts and includes to customize the entire site layout.
### Default layout and includable components
The `default` layout is inherited by most of the "out-of-the-box" pages provided by Just the Docs. It composes various re-usable components of the site, including the sidebar, navbar, footer, breadcrumbs, and various imports. Most users who create new pages or layouts will inherit from `default`.
Here is a simplified code example of what it looks like:
{% raw %}
```liquid
<!-- a simplified version of _layouts/default.html -->
<html>
{% include head.html %}
<body>
{% include icons/icons.html %}
{% include components/sidebar.html %}
{% include components/header.html %}
{% include components/breadcrumbs.html %}
{% if site.heading_anchors != false %}
{% include vendor/anchor_headings.html html=content ... %}
{% else %}
{{ content }}
{% endif %}
{% if page.has_children == true and page.has_toc != false %}
{% include components/children_nav.html %}
{% endif %}
{% include components/footer.html %}
{% if site.search_enabled != false %}
{% include components/search_footer.html %}
{% endif %}
{% if site.mermaid %}
{% include components/mermaid.html %}
{% endif %}
</body>
</html>
```
{% endraw %}
#### Component summary
{: .no_toc }
{: .warning }
Defining a new `_includes` with the same name as any of these components will significantly change the existing layout. Please proceed with caution when adjusting them.
To briefly summarize each component:
- `_includes/head.html` is the entire `<head>` tag for the site; this imports stylesheets, various JavaScript files (ex: analytics, mermaid, search, and Just the Docs code), and SEO / meta information.
- `_includes/icons/icons.html` imports all SVG icons that are used throughout the site. Some, such as those relating to search or code snippet copying, are only loaded when those features are enabled.
- `_includes/components/sidebar.html` renders the sidebar, containing the site header, navigation links, external links, collections, and nav footer.
- `_includes/components/header.html` renders the navigation header, containing the search bar, custom header, and aux links
- `_includes/components/breadcrumbs.html` renders the breadcrumbs feature
- `vendor/anchor_headings.html` is a local copy of Vladimir Jimenez's [jekyll-anchor-headings](https://github.com/allejo/jekyll-anchor-headings) snippet
- `_includes/components/children_nav.html` renders a list of nav links to child pages on parent pages
- `_includes/components/footer.html` renders the bottom-of-page footer
- `_includes/components/search_footer.html` renders DOM elements that are necessary for the search bar to work
- `_includes/components/mermaid.html` initializes mermaid if the feature is enabled
Each of these components can be overridden individually using the same process described in the [Override includes](#override-includes) section. In particular, the granularity of components should allow users to replace certain components (such as the sidebar) without having to adjust the rest of the code.
Future versions may subdivide components further; we guarantee that we will only place them in folders (ex `components/`, `icons/`, or a new `js/`) to avoid top-level namespace collisions.
### Alternative layouts and example (`minimal`)
Users can develop custom layouts that compose, omit, or add components differently. We provide one first-class example titled `minimal`, inspired by Kevin Lin's work in [just-the-class](https://github.com/kevinlin1/just-the-class). This `minimal` layout does not render the sidebar, header, or search. To see an example, visit the [minimal layout test]({{site.baseurl}}/docs/minimal-test/) page.
Here is a simplified code example of what it looks like:
{% raw %}
```liquid
<!-- a simplified version of _layouts/minimal.html -->
<html>
{% include head.html %}
<body>
{% include icons/icons.html %}
{% comment %} Bandaid fix for breadcrumbs here! {% endcomment %}
{% include components/breadcrumbs.html %}
{% if site.heading_anchors != false %}
{% include vendor/anchor_headings.html html=content ... %}
{% else %}
{{ content }}
{% endif %}
{% if page.has_children == true and page.has_toc != false %}
{% include components/children_nav.html %}
{% endif %}
{% include components/footer.html %}
{% if site.mermaid %}
{% include components/mermaid.html %}
{% endif %}
</body>
</html>
```
{% endraw %}
This layout is packaged in Just the Docs. Users can indicate this alternative layout in page front matter:
{% raw %}
```
---
layout: minimal
title: Minimal layout test
---
```
{% endraw %}
Similarly, users and developers can create other alternative layouts using Just the Docs' reusable includable components.
### Default layout and inheritance chain
Under the hood,
- `default` and `minimal` inherit from the `table_wrappers` layout, which wraps all HTML `<table>` tags with a `div .table-wrapper`
- `table_wrappers` inherits from `vendor/compress`, which is a local copy of Anatol Broder's [jekyll-compress-html](https://github.com/penibelst/jekyll-compress-html) Jekyll plugin
Note that as of now, `minimal` and `default` have no inheritance relationship.
### Overridden default Jekyll layouts
By default, Jekyll (and its default theme `minima`) provide the `about`, `home`, `page`, and `post` layouts. In Just the Docs, we override all of these layouts with the `default` layout. Each of those layouts is simply:
{% raw %}
```
---
layout: default
---
{{ content }}
```
{% endraw %}
docs/minimal-test.md deleted 100644 → 0
+ 0
− 9
View file @ bab51830
---
layout: minimal
title: Minimal layout test
nav_exclude: true
---
[Return to main website]({{site.baseurl}}/).
This page demonstrates the packaged `minimal` layout, which does not render the sidebar or header. It can be used for standalone pages. It is also an example of using the new modular site components to define custom layouts; see ["Custom layouts and includes" in the customization docs]({{site.baseurl}}/docs/customization/#custom-layouts-and-includes) for more information.
docs/navigation-structure.md deleted 100644 → 0
+ 0
− 317
View file @ bab51830
---
layout: default
title: Navigation Structure
nav_order: 5
nav_exclude: true
---
# Navigation Structure
{: .no_toc }
<details open markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
- TOC
{:toc}
</details>
---
## Main navigation
The main navigation for your Just the Docs site is on the left side of the page at large screens and on the top (behind a tap) on small screens. The main navigation can be structured to accommodate a multi-level menu system (pages with children and grandchildren).
By default, all pages will appear as top level pages in the main nav unless a parent page is defined (see [Pages with Children](#pages-with-children)).
---
## Ordering pages
To specify a page order, you can use the `nav_order` parameter in your pages' YAML front matter.
#### Example
{: .no_toc }
```yaml
---
layout: default
title: Customization
nav_order: 4
---
```
The parameter values determine the order of the top-level pages, and of child pages with the same parent. You can reuse the same parameter values (e.g., integers starting from 1) for the child pages of different parents.
The parameter values can be numbers (integers, floats) and/or strings. Pages with numerical `nav_order` parameters always come before those with string `nav_order` parameters. When you omit `nav_order` parameters, they default to the titles of the pages. If you want to make the page order independent of the page titles, you can set explicit `nav_order` parameters on all pages. All pages with explicit `nav_order` parameters
come before all pages ordered by their `title` values.
By default, all Capital letters come before all lowercase letters; you can add `nav_sort: case_insensitive` in the configuration file to ignore the case. Enclosing strings in (single or double) quotation marks is optional. Numeric values are not enclosed in quotation marks, e.g., `42`, `-1.0`; numbers in quotation marks are lexicographically ordered, so `"10"` comes before `"2"`, for example.
---
## Excluding pages
For specific pages that you do not wish to include in the main navigation, e.g. a 404 page or a landing page, use the `nav_exclude: true` parameter in the YAML front matter for that page.
#### Example
{: .no_toc }
```yaml
---
layout: default
title: 404
nav_exclude: true
---
```
The `nav_exclude` parameter does not affect the [auto-generating list of child pages](#auto-generating-table-of-contents), which you can use to access pages excluded from the main navigation.
Pages with no `title` are automatically excluded from the main navigation.
---
## Pages with children
Sometimes you will want to create a page with many children (a section). First, it is recommended that you keep pages that are related in a directory together... For example, in these docs, we keep all of the written documentation in the `./docs` directory and each of the sections in subdirectories like `./docs/ui-components` and `./docs/utilities`. This gives us an organization like:
```
+-- ..
|-- (Jekyll files)
|
|-- docs
| |-- ui-components
| | |-- index.md (parent page)
| | |-- buttons.md
| | |-- code.md
| | |-- labels.md
| | |-- tables.md
| | +-- typography.md
| |
| |-- utilities
| | |-- index.md (parent page)
| | |-- color.md
| | |-- layout.md
| | |-- responsive-modifiers.md
| | +-- typography.md
| |
| |-- (other md files, pages with no children)
| +-- ..
|
|-- (Jekyll files)
+-- ..
```
On the parent pages, add this YAML front matter parameter:
- `has_children: true` (tells us that this is a parent page)
#### Example
{: .no_toc }
```yaml
---
layout: default
title: UI Components
nav_order: 2
has_children: true
---
```
Here we're setting up the UI Components landing page that is available at `/docs/ui-components`, which has children and is ordered second in the main nav.
### Child pages
{: .text-gamma }
On child pages, simply set the `parent:` YAML front matter to whatever the parent's page title is and set a nav order (this number is now scoped within the section).
#### Example
{: .no_toc }
```yaml
---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
---
```
The Buttons page appears as a child of UI Components and appears second in the UI Components section.
### Ordering child pages
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
You can optionally add the following to the YAML front matter to reverse the default sort order of child pages:
- `child_nav_order: reversed`
#### Example
{: .no_toc }
```yaml
---
layout: default
title: Reversed Child Pages
child_nav_order: reversed
---
```
### Auto-generating Table of Contents
By default, all pages with children will automatically append a Table of Contents which lists the child pages after the parent page's content. To disable this auto Table of Contents, set `has_toc: false` in the parent page's YAML front matter.
#### Example
{: .no_toc }
```yaml
---
layout: default
title: UI Components
nav_order: 2
has_children: true
has_toc: false
---
```
### Children with children
{: .text-gamma }
Child pages can also have children (grandchildren). This is achieved by using a similar pattern on the child and grandchild pages.
1. Add the `has_children` attribute to the child
1. Add the `parent` and `grand_parent` attribute to the grandchild
#### Example
{: .no_toc }
```yaml
---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
has_children: true
---
```
```yaml
---
layout: default
title: Buttons Child Page
parent: Buttons
grand_parent: UI Components
nav_order: 1
---
```
This would create the following navigation structure:
```
+-- ..
|
|-- UI Components
| |-- ..
| |
| |-- Buttons
| | |-- Button Child Page
| |
| |-- ..
|
+-- ..
```
{: .note }
Currently, the navigation structure is limited to 3 levels: grandchild pages cannot themselves have child pages.
---
## Auxiliary Links
To add auxiliary links to your site (in the upper right on all pages), add it to the `aux_links` [configuration option]({% link docs/configuration.md %}#aux-links) in your site's `_config.yml` file.
#### Example
{: .no_toc }
```yaml
# Aux links for the upper right navigation
aux_links:
"Just the Docs on GitHub":
- "//github.com/just-the-docs/just-the-docs"
```
---
## External Navigation Links
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
To add external links to the navigation, add them to the `nav_external_links` [configuration]({% link docs/configuration.md %}) option in your site's `_config.yml` file.
External links will appear in the navigation after the links to ordinary pages, but before any collections.
#### Example
{: .no_toc }
```yaml
# External navigation links
nav_external_links:
- title: Just the Docs on GitHub
url: https://github.com/just-the-docs/just-the-docs
hide_icon: false # set to true to hide the external link icon - defaults to false
```
The external links are decorated by an icon, which distinguishes them from internal links.
You can suppress the icon by setting `hide_icon: true`.
---
## In-page navigation with Table of Contents
To generate a Table of Contents on your docs pages, you can use the `{:toc}` method from Kramdown, immediately after an `<ol>` in Markdown. This will automatically generate an ordered list of anchor links to various sections of the page based on headings and heading levels. There may be occasions where you're using a heading and you don't want it to show up in the TOC, so to skip a particular heading use the `{: .no_toc }` CSS class.
#### Example
{: .no_toc }
```markdown
# Navigation Structure
{: .no_toc }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
```
This example skips the page name heading (`#`) from the TOC, as well as the heading for the Table of Contents itself (`##`) because it is redundant, followed by the table of contents itself. To get an unordered list, replace `1. TOC` above by `- TOC`.
### Collapsible Table of Contents
The Table of Contents can be made collapsible using the `<details>` and `<summary>` elements , as in the following example. The attribute `open` (expands the Table of Contents by default) and the styling with `{: .text-delta }` are optional.
```markdown
<details open markdown="block">
<summary>
Table of contents
</summary>
{: .text-delta }
1. TOC
{:toc}
</details>
```
The result is shown at [the top of this page](#navigation-structure) (`{:toc}` can be used only once on each page).
docs/ui-components/buttons.md deleted 100644 → 0
+ 0
− 98
View file @ bab51830
---
layout: default
title: Buttons
parent: UI Components
nav_order: 2
nav_exclude: true
---
# Buttons
{: .no_toc }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
## Basic button styles
### Links that look like buttons
<div class="code-example" markdown="1">
[Link button](http://example.com/){: .btn }
[Link button](http://example.com/){: .btn .btn-purple }
[Link button](http://example.com/){: .btn .btn-blue }
[Link button](http://example.com/){: .btn .btn-green }
[Link button](http://example.com/){: .btn .btn-outline }
</div>
```markdown
[Link button](http://example.com/){: .btn }
[Link button](http://example.com/){: .btn .btn-purple }
[Link button](http://example.com/){: .btn .btn-blue }
[Link button](http://example.com/){: .btn .btn-green }
[Link button](http://example.com/){: .btn .btn-outline }
```
### Button element
GitHub Flavored Markdown does not support the `button` element, so you'll have to use inline HTML for this:
<div class="code-example">
<button type="button" name="button" class="btn">Button element</button>
</div>
```html
<button type="button" name="button" class="btn">Button element</button>
```
---
## Using utilities with buttons
### Button size
Wrap the button in a container that uses the [font-size utility classes]({% link docs/utilities/typography.md %}) to scale buttons:
<div class="code-example" markdown="1">
<span class="fs-6">
[Big ass button](http://example.com/){: .btn }
</span>
<span class="fs-3">
[Tiny ass button](http://example.com/){: .btn }
</span>
</div>
```markdown
<span class="fs-8">
[Link button](http://example.com/){: .btn }
</span>
<span class="fs-3">
[Tiny ass button](http://example.com/){: .btn }
</span>
```
### Spacing between buttons
Use the [margin utility classes]({% link docs/utilities/layout.md %}#spacing) to add spacing between two buttons in the same block.
<div class="code-example" markdown="1">
[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
[Button](http://example.com/){: .btn .btn-blue }
[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
[Button](http://example.com/){: .btn .btn-blue }
</div>
```markdown
[Button with space](http://example.com/){: .btn .btn-purple .mr-2 }
[Button](http://example.com/){: .btn .btn-blue }
[Button with more space](http://example.com/){: .btn .btn-green .mr-4 }
[Button](http://example.com/){: .btn .btn-blue }
```
docs/ui-components/callouts 2.md deleted 100644 → 0
+ 0
− 162
View file @ bab51830
---
layout: default
title: Callouts
parent: UI Components
nav_order: 7
nav_exclude: true
---
# Callouts
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes).
Common kinds of callouts include `highlight`, `important`, `new`, `note`, and `warning`.
{: .warning }
These callout names are *not* pre-defined by the theme: you need to define your own names.
When you have [configured]({% link docs/configuration.md %}#callouts) the `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix]
[^postfix]:
You can put the callout markup either before or after its content.
#### An untitled callout
{: .no_toc }
```markdown
{: .highlight }
A paragraph
```
{: .highlight }
A paragraph
#### A single paragraph callout
{: .no_toc }
```markdown
{: .note }
A paragraph
```
{: .note }
A paragraph
```markdown
{: .note-title }
> My note title
>
> A paragraph with a custom title callout
```
{: .note-title }
> My note title
>
> A paragraph with a custom title callout
#### A multi-paragraph callout
{: .no_toc }
```markdown
{: .important }
> A paragraph
>
> Another paragraph
>
> The last paragraph
```
{: .important }
> A paragraph
>
> Another paragraph
>
> The last paragraph
```markdown
{: .important-title }
> My important title
>
> A paragraph
>
> Another paragraph
>
> The last paragraph
```
{: .important-title }
> My important title
>
> A paragraph
>
> Another paragraph
>
> The last paragraph
#### An indented callout
{: .no_toc }
```markdown
> {: .highlight }
A paragraph
```
> {: .highlight }
A paragraph
#### Indented multi-paragraph callouts
{: .no_toc }
```markdown
> {: .new }
> > A paragraph
> >
> > Another paragraph
> >
> > The last paragraph
```
> {: .new }
> > A paragraph
> >
> > Another paragraph
> >
> > The last paragraph
#### Nested callouts
{: .no_toc }
```markdown
{: .important }
> {: .warning }
> A paragraph
```
{: .important }
> {: .warning }
> A paragraph
#### Opaque background
{: .no_toc }
```markdown
{: .important }
> {: .opaque }
> <div markdown="block">
> {: .warning }
> A paragraph
> </div>
```
{: .important }
> {: .opaque }
> <div markdown="block">
> {: .warning }
> A paragraph
> </div>
docs/ui-components/callouts.md deleted 100644 → 0
+ 0
− 162
View file @ bab51830
---
layout: default
title: Callouts
parent: UI Components
nav_order: 7
nav_exclude: true
---
# Callouts
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
Markdown does not include support for callouts. However, you can style text as a callout using a Markdown extension supported by kramdown: [*block IALs*](https://kramdown.gettalong.org/quickref.html#block-attributes).
Common kinds of callouts include `highlight`, `important`, `new`, `note`, and `warning`.
{: .warning }
These callout names are *not* pre-defined by the theme: you need to define your own names.
When you have [configured]({% link docs/configuration.md %}#callouts) the `color` and (optional) `title` for a callout, you can apply it to a paragraph, or to a block quote with several paragraphs, as illustrated below.[^postfix]
[^postfix]:
You can put the callout markup either before or after its content.
#### An untitled callout
{: .no_toc }
```markdown
{: .highlight }
A paragraph
```
{: .highlight }
A paragraph
#### A single paragraph callout
{: .no_toc }
```markdown
{: .note }
A paragraph
```
{: .note }
A paragraph
```markdown
{: .note-title }
> My note title
>
> A paragraph with a custom title callout
```
{: .note-title }
> My note title
>
> A paragraph with a custom title callout
#### A multi-paragraph callout
{: .no_toc }
```markdown
{: .important }
> A paragraph
>
> Another paragraph
>
> The last paragraph
```
{: .important }
> A paragraph
>
> Another paragraph
>
> The last paragraph
```markdown
{: .important-title }
> My important title
>
> A paragraph
>
> Another paragraph
>
> The last paragraph
```
{: .important-title }
> My important title
>
> A paragraph
>
> Another paragraph
>
> The last paragraph
#### An indented callout
{: .no_toc }
```markdown
> {: .highlight }
A paragraph
```
> {: .highlight }
A paragraph
#### Indented multi-paragraph callouts
{: .no_toc }
```markdown
> {: .new }
> > A paragraph
> >
> > Another paragraph
> >
> > The last paragraph
```
> {: .new }
> > A paragraph
> >
> > Another paragraph
> >
> > The last paragraph
#### Nested callouts
{: .no_toc }
```markdown
{: .important }
> {: .warning }
> A paragraph
```
{: .important }
> {: .warning }
> A paragraph
#### Opaque background
{: .no_toc }
```markdown
{: .important }
> {: .opaque }
> <div markdown="block">
> {: .warning }
> A paragraph
> </div>
```
{: .important }
> {: .opaque }
> <div markdown="block">
> {: .warning }
> A paragraph
> </div>
docs/ui-components/code 2.md deleted 100644 → 0
+ 0
− 175
View file @ bab51830
---
layout: default
title: Code
parent: UI Components
has_children: true
nav_order: 6
nav_exclude: true
---
# Code
{: .no_toc }
## Table of contents
{: .no_toc .text-delta }
1. TOC
{:toc}
---
## Inline code
Code can be rendered inline by wrapping it in single back ticks.
<div class="code-example" markdown="1">
Lorem ipsum dolor sit amet, `<inline code snippet>` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
## Heading with `<inline code snippet>` in it.
{: .no_toc }
</div>
```markdown
Lorem ipsum dolor sit amet, `<inline code snippet>` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
## Heading with `<inline code snippet>` in it.
```
---
## Syntax highlighted code blocks
Use Jekyll's built-in syntax highlighting with Rouge for code blocks by using three backticks, followed by the language name:
<div class="code-example" markdown="1">
```js
// Javascript code with syntax highlighting.
var fun = function lang(l) {
dateformat.i18n = require('./lang/' + l)
return true;
}
```
</div>
{% highlight markdown %}
```js
// Javascript code with syntax highlighting.
var fun = function lang(l) {
dateformat.i18n = require('./lang/' + l)
return true;
}
```
{% endhighlight %}
---
## Code blocks with rendered examples
To demonstrate front end code, sometimes it's useful to show a rendered example of that code. After including the styles from your project that you'll need to show the rendering, you can use a `<div>` with the `code-example` class, followed by the code block syntax. If you want to render your output with Markdown instead of HTML, use the `markdown="1"` attribute to tell Jekyll that the code you are rendering will be in Markdown format... This is about to get meta...
<div class="code-example" markdown="1">
<div class="code-example" markdown="1">
[Link button](http://example.com/){: .btn }
</div>
```markdown
[Link button](http://example.com/){: .btn }
```
</div>
{% highlight markdown %}
<div class="code-example" markdown="1">
[Link button](http://example.com/){: .btn }
</div>
```markdown
[Link button](http://example.com/){: .btn }
```
{% endhighlight %}
---
## Mermaid diagram code blocks
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. **It is disabled by default**. However, you can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`.
The minimum configuration requires a `version` key (matching a version in [jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)):
```yaml
mermaid:
# Version of mermaid library
# Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
version: "9.1.3"
```
Additional configuration options are loaded through `_includes/mermaid_config.js`. By default, the contents of the file are the empty object:
```js
// _includes/mermaid_config.js
{}
```
This loads the default settings.
The contents of this object should follow [mermaid's configuration API](https://mermaid-js.github.io/mermaid/#/./Setup?id=configuration). For example, to override the theme, change `_includes/mermaid_config.js` to:
```js
// _includes/mermaid_config.js
{
theme: "forest"
}
```
Once mermaid is installed, it can be used in markdown files. The markdown for a simple flowchart example might look like the following:
{% highlight markdown %}
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
{% endhighlight %}
which renders:
```mermaid
graph TD;
A-->B;
A-->C;
B-->D;
C-->D;
```
*Note: for demonstration purposes, we've enabled mermaid on this site. It is still disabled by default, and users need to opt-in to use it.*
### Using a local mermaid library
In order to use a local version of the mermaid library instead of one provided by jsDelivr, you can specify a `path` key in the mermaid configuration instead of a `version` key.
```yaml
mermaid:
# To load mermaid from a local file use the `path` key to specify the location of the library instead; e.g.
path: "/assets/js/mermaid.min.js"
```
## Copy button
{: .d-inline-block }
New (v0.4.0)
{: .label .label-green }
The copy button for code blocks can be enabled or disabled via the `enable_copy_code_button` key in `_config.yml`. By default, the value of this key is `false`; users need to opt-in.
```yaml
# For copy button on code
enable_copy_code_button: true
```
Note that this feature requires JavaScript; if JavaScript is disabled in the browser, this feature will not work.
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment