diff --git a/.gitignore b/.gitignore index ede2c28..6a93429 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # Not sure what a .gitignore is? -# See: https://git-scm.com/docs/gitignore +# See: https://git-scm.com/gitignore # The first files are directly copied from Jekyll's first-party docs on `.gitignore` files: # https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control diff --git a/_includes/fix_linenos.html b/_includes/fix_linenos.html index 9af369e..f2adbe6 100644 --- a/_includes/fix_linenos.html +++ b/_includes/fix_linenos.html @@ -5,7 +5,7 @@ a `` element within a `` block). As such, we no longer recommend using this workaround. For more information, see the "Code snippets with line numbers" docs page: -https://just-the-docs.com/docs/ui-components/code/line-numbers/ +https://just-the-docs.com/ui-components/code/line-numbers/ (or, docs/ui-components/line-nos.md/) The next portion of this file, including the comments and the workaround, diff --git a/docs/contributing/PR_acceptance_criteria.md b/contributing/PR_acceptance_criteria.md similarity index 95% rename from docs/contributing/PR_acceptance_criteria.md rename to contributing/PR_acceptance_criteria.md index e684324..8b7afd5 100644 --- a/docs/contributing/PR_acceptance_criteria.md +++ b/contributing/PR_acceptance_criteria.md @@ -3,7 +3,7 @@ layout: default title: PR Acceptance criteria parent: Contributing grand_parent: Developing -permalink: /docs/developing/contributing/PR_acceptance_criteria +permalink: /developing/contributing/PR_acceptance_criteria nav_order: 4 --- diff --git a/docs/contributing/branch_and_commit_guidelines.md b/contributing/branch_and_commit_guidelines.md similarity index 95% rename from docs/contributing/branch_and_commit_guidelines.md rename to contributing/branch_and_commit_guidelines.md index 39ee5fa..3ff4a11 100644 --- a/docs/contributing/branch_and_commit_guidelines.md +++ b/contributing/branch_and_commit_guidelines.md @@ -3,7 +3,7 @@ layout: default title: Branch and Commit Guidelines parent: Contributing grand_parent: Developing -permalink: /docs/developing/contributing/branch_and_commit_guidelines +permalink: /developing/contributing/branch_and_commit_guidelines nav_order: 2 --- diff --git a/docs/contributing/contributing.md b/contributing/contributing.md similarity index 95% rename from docs/contributing/contributing.md rename to contributing/contributing.md index c86fe84..e0b6178 100644 --- a/docs/contributing/contributing.md +++ b/contributing/contributing.md @@ -3,7 +3,7 @@ layout: default title: Contributing parent: Developing has_children: true -permalink: /docs/developing/contributing/ +permalink: /developing/contributing/ nav_order: 6 --- diff --git a/docs/contributing/contributing_process.md b/contributing/contributing_process.md similarity index 69% rename from docs/contributing/contributing_process.md rename to contributing/contributing_process.md index 39c156f..4e7cc5b 100644 --- a/docs/contributing/contributing_process.md +++ b/contributing/contributing_process.md @@ -3,7 +3,7 @@ layout: default title: Contributing process grand_parent: Developing parent: Contributing -permalink: /docs/developing/contributing/contributing_process +permalink: /developing/contributing/contributing_process nav_order: 1 --- @@ -24,18 +24,18 @@ nav_order: 1 ### Follow Development guide -Follow the [Setting development environment]({{site.baseurl}}/docs/developing/setting_development_environment/) to set up the project. Consider you will have to fork the project you want to contribute to. +Follow the [Setting development environment]({{site.baseurl}}/developing/setting_development_environment/) to set up the project. Consider you will have to fork the project you want to contribute to. ### Create a new branch -Create a new [branch]({{site.baseurl}}/docs/contributing/branch_and_commit_guidelines/#branch-naming-conventions) from develop in your forked project. +Create a new [branch]({{site.baseurl}}/contributing/branch_and_commit_guidelines/#branch-naming-conventions) from develop in your forked project. ``` git branch new-branch develop ``` ### Make an empty commit -Make an [empty commit]({{site.baseurl}}/docs/contributing/branch_and_commit_guidelines/#first-commit-requirements) on this branch and push. +Make an [empty commit]({{site.baseurl}}/contributing/branch_and_commit_guidelines/#first-commit-requirements) on this branch and push. ```bash git commit -m 'message' --allow-empty git push -u origin new-branch diff --git a/docs/contributing/errors_and_issues.md b/contributing/errors_and_issues.md similarity index 89% rename from docs/contributing/errors_and_issues.md rename to contributing/errors_and_issues.md index 6730ed6..c51e797 100644 --- a/docs/contributing/errors_and_issues.md +++ b/contributing/errors_and_issues.md @@ -3,7 +3,7 @@ layout: default title: Errors and issues parent: Contributing grand_parent: Developing -permalink: /docs/developing/contributing/errors_and_issues +permalink: /developing/contributing/errors_and_issues nav_order: 3 --- @@ -21,7 +21,7 @@ nav_order: 3 ### Errors outside the scope of your work 1. Make sure it is an actual error and not a bad interaction between your code and the rest of the project. -2. [Open an issue]({{site.baseurl}}/docs/contributing/errors_and_issues/#guidelines-for-creating-issues) to keep track of the error. +2. [Open an issue]({{site.baseurl}}/contributing/errors_and_issues/#guidelines-for-creating-issues) to keep track of the error. 3. You can assign the issue yourself if you either want to fix the error or need to do so for your code to work. If you want to fix that new issue, you SHOULD do it from a different PR. If it is impossible or too hard to separately fix it, fix the error on your already open PR, but you MUST clarify which commits are part of this new issue so maintainers know it when squashing. ### Errors in your own code diff --git a/docs/core_and_plugins/bdd.md b/core_and_plugins/bdd.md similarity index 100% rename from docs/core_and_plugins/bdd.md rename to core_and_plugins/bdd.md diff --git a/docs/core_and_plugins/core.md b/core_and_plugins/core.md similarity index 100% rename from docs/core_and_plugins/core.md rename to core_and_plugins/core.md diff --git a/docs/core_and_plugins/core_and_plugins.md b/core_and_plugins/core_and_plugins.md similarity index 77% rename from docs/core_and_plugins/core_and_plugins.md rename to core_and_plugins/core_and_plugins.md index 34ac2c8..f29aae1 100644 --- a/docs/core_and_plugins/core_and_plugins.md +++ b/core_and_plugins/core_and_plugins.md @@ -2,7 +2,7 @@ layout: default title: Core and plugins has_children: true -permalink: /docs/core_and_plugins +permalink: /core_and_plugins nav_order: 3 --- diff --git a/docs/core_and_plugins/fm.md b/core_and_plugins/fm.md similarity index 100% rename from docs/core_and_plugins/fm.md rename to core_and_plugins/fm.md diff --git a/docs/core_and_plugins/lab plugins/bdd_colosal_fm.md b/core_and_plugins/lab plugins/bdd_colosal_fm.md similarity index 100% rename from docs/core_and_plugins/lab plugins/bdd_colosal_fm.md rename to core_and_plugins/lab plugins/bdd_colosal_fm.md diff --git a/docs/core_and_plugins/lab plugins/lab_plugins.md b/core_and_plugins/lab plugins/lab_plugins.md similarity index 73% rename from docs/core_and_plugins/lab plugins/lab_plugins.md rename to core_and_plugins/lab plugins/lab_plugins.md index cd291a4..93fd43a 100644 --- a/docs/core_and_plugins/lab plugins/lab_plugins.md +++ b/core_and_plugins/lab plugins/lab_plugins.md @@ -3,7 +3,7 @@ layout: default title: Lab plugins parent: Core and plugins has_children: true -permalink: /docs/core_and_plugins/lab_plugins/ +permalink: /core_and_plugins/lab_plugins/ nav_order: 5 --- diff --git a/docs/core_and_plugins/pysat.md b/core_and_plugins/pysat.md similarity index 100% rename from docs/core_and_plugins/pysat.md rename to core_and_plugins/pysat.md diff --git a/docs/developing/cli.md b/developing/cli.md similarity index 93% rename from docs/developing/cli.md rename to developing/cli.md index 31174df..7b6943e 100644 --- a/docs/developing/cli.md +++ b/developing/cli.md @@ -17,7 +17,7 @@ nav_order: 2 {:toc} {: .important } -> In order to use the CLI, you need to [set the development environment]({{site.baseurl}}/docs/developing/setting_development_environment/) +> In order to use the CLI, you need to [set the development environment]({{site.baseurl}}/developing/setting_development_environment/) ## Get availables plugins diff --git a/docs/developing/developing.md b/developing/developing.md similarity index 94% rename from docs/developing/developing.md rename to developing/developing.md index 47985e8..4b6f081 100644 --- a/docs/developing/developing.md +++ b/developing/developing.md @@ -2,7 +2,7 @@ layout: default title: Developing has_children: true -permalink: /docs/developing +permalink: /developing nav_order: 4 --- diff --git a/docs/developing/extending_with_your_plugins.md b/developing/extending_with_your_plugins.md similarity index 90% rename from docs/developing/extending_with_your_plugins.md rename to developing/extending_with_your_plugins.md index aaee4a9..a2b34af 100644 --- a/docs/developing/extending_with_your_plugins.md +++ b/developing/extending_with_your_plugins.md @@ -15,7 +15,7 @@ nav_order: 2 {:toc} {: .important } -> In order to use the CLI, you need to [set the development environment]({{site.baseurl}}/docs/developing/setting_development_environment/) +> In order to use the CLI, you need to [set the development environment]({{site.baseurl}}/developing/setting_development_environment/) ## Create your own plugin diff --git a/docs/developing/integrating_with_your_tools.md b/developing/integrating_with_your_tools.md similarity index 100% rename from docs/developing/integrating_with_your_tools.md rename to developing/integrating_with_your_tools.md diff --git a/docs/developing/setting_development_environment.md b/developing/setting_development_environment.md similarity index 100% rename from docs/developing/setting_development_environment.md rename to developing/setting_development_environment.md diff --git a/docs/developing/testing_plugins.md b/developing/testing_plugins.md similarity index 100% rename from docs/developing/testing_plugins.md rename to developing/testing_plugins.md diff --git a/docs_old/configuration.md b/docs_old/configuration.md deleted file mode 100644 index 5a9ecff..0000000 --- a/docs_old/configuration.md +++ /dev/null @@ -1,340 +0,0 @@ ---- -layout: default -title: Configuration -nav_order: 20 ---- - -# 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 - # Focus the search input by pressing `ctrl + focus_shortcut_key` (or `cmd + focus_shortcut_key` on macOS) - focus_shortcut_key: 'k' -``` - -## 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 -``` - -## Navigation sidebar - -```yaml -# Enable or disable the side/mobile menu globally -# Nav menu can also be selectively enabled or disabled using page variables or the minimal layout -nav_enabled: true -``` - -## 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 © 2017-2020 Patrick Marsceill. Distributed by an MIT license." - -# 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 -``` - - - - - -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. - -New (v0.4.0){: .label .label-green } -Including `nav_fold: true` in a collection configuration *folds* that collection: -an expander symbol appears next to the collection name, -and clicking it displays/hides the links to the top-level pages of the collection.[^js-disabled] - -[^js-disabled]: New (v0.6.0){: .label .label-green } - When JavaScript is disabled in the browser, all folded collections are automatically expanded, - since clicking expander symbols has no effect. - (In previous releases, navigation into folded collections required JavaScript to be enabled.) - -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. diff --git a/docs_old/customization.md b/docs_old/customization.md deleted file mode 100644 index 4939e18..0000000 --- a/docs_old/customization.md +++ /dev/null @@ -1,372 +0,0 @@ ---- -layout: default -title: Customization -nav_order: 6 ---- - -# 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 -``` - - - - - -### deprecated: `legacy_light` -{: .d-inline-block .no_toc } - -New (v0.4.2) -{: .label .label-green } - - -In Just the Docs version `0.4.2`, we changed the default syntax highlighting theme for the `light` color scheme to have higher contrast. Users who want to use the old highlighting need to explicitly opt-in with the deprecated `legacy_light` color scheme. In a future major release of Just the Docs, we will remove this color scheme. - -## 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 or functions, place SCSS code in `_sass/custom/setup.scss`. This should *not* be used for defining custom styles (see the next section) or overriding color scheme variables (in this case, you should create a new color scheme). - -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 -

Contents

-``` - -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 `` tag. This might include additional ``, ``, or ` - -Text can be **bold**, _italic_, or ~~strikethrough~~. - -[Link to another page]({{site.baseurl}}/). - -There should be whitespace between paragraphs. - -There should be whitespace between paragraphs. We recommend including a README, or a file with information about your project. - -# [](#header-1)Header 1 - -This is a normal paragraph following a header. GitHub is a code hosting platform for version control and collaboration. It lets you and others work together on projects from anywhere. - -## [](#header-2)Header 2 - -> This is a blockquote following a header. -> -> When something is important enough, you do it even if the odds are not in your favor. - -### [](#header-3)Header 3 - -```js -// Javascript code with syntax highlighting. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l) - return true; -} -``` - -```ruby -# Ruby code with syntax highlighting -GitHubPages::Dependencies.gems.each do |gem, version| - s.add_dependency(gem, "= #{version}") -end -``` - -#### [](#header-4-with-code-not-transformed)Header 4 `with code not transformed` - -* This is an unordered list following a header. -* This is an unordered list following a header. -* This is an unordered list following a header. - -##### [](#header-5)Header 5 - -1. This is an ordered list following a header. -2. This is an ordered list following a header. -3. This is an ordered list following a header. - -###### [](#header-6)Header 6 - -[This is a very long link which wraps and therefore doesn't overflow -even when it comes at the beginning](.) of the line. - -- [This is a very long link which wraps and therefore doesn't overflow the line - when used first in an item ](.) in a list. - -| head1 | head two | three | -|:-------------|:------------------|:------| -| ok | good swedish fish | nice | -| out of stock | good and plenty | nice | -| ok | good `oreos` | hmm | -| ok | good `zoute` drop | yumm | - -### There's a horizontal rule below this. - -* * * - -### Here is an unordered list: - -* Item foo -* Item bar -* Item baz -* Item zip - -### And an ordered list: - -1. Item one -1. Item two -1. Item three -1. Item four - -### And an ordered list, continued: - -1. Item one -1. Item two - -Some text - -{:style="counter-reset:none"} -1. Item three -1. Item four - -### And an ordered list starting from 42: - -{:style="counter-reset:step-counter 41"} -1. Item 42 -1. Item 43 -1. Item 44 - -### And a nested list: - -- level 1 item - - level 2 item - - level 2 item - - level 3 item - - level 3 item -- level 1 item - - level 2 item - - level 2 item - - level 2 item -- level 1 item - - level 2 item - - level 2 item -- level 1 item - -### Nesting an ol in ul in an ol - -- level 1 item (ul) - 1. level 2 item (ol) - 1. level 2 item (ol) - - level 3 item (ul) - - level 3 item (ul) -- level 1 item (ul) - 1. level 2 item (ol) - 1. level 2 item (ol) - - level 3 item (ul) - - level 3 item (ul) - 1. level 4 item (ol) - 1. level 4 item (ol) - - level 3 item (ul) - - level 3 item (ul) -- level 1 item (ul) - -### And a task list - -- [ ] Hello, this is a TODO item -- [ ] Hello, this is another TODO item -- [x] Goodbye, this item is done - -### Nesting task lists - -- [ ] level 1 item (task) - - [ ] level 2 item (task) - - [ ] level 2 item (task) -- [ ] level 1 item (task) -- [ ] level 1 item (task) - -### Nesting a ul in a task list - -- [ ] level 1 item (task) - - level 2 item (ul) - - level 2 item (ul) -- [ ] level 1 item (task) -- [ ] level 1 item (task) - -### Nesting a task list in a ul - -- level 1 item (ul) - - [ ] level 2 item (task) - - [ ] level 2 item (task) -- level 1 item (ul) -- level 1 item (ul) - -### Small image - -![](../../assets/images/small-image.jpg) - -### Large image - -![](../../assets/images/large-image.jpg) - -"[Wroclaw University Library digitizing rare archival texts](https://www.flickr.com/photos/97810305@N08/9401451269)" by [j_cadmus](https://www.flickr.com/photos/97810305@N08) is marked with [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/?ref=openverse). - -### Labels - -I'm a label -{: .label } - -blue -{: .label .label-blue } -green -{: .label .label-green } -purple -{: .label .label-purple } -yellow -{: .label .label-yellow } -red -{: .label .label-red } - -**bold** -{: .label } -*italic* -{: .label } -***bold + italic*** -{: .label } - -### Definition lists can be used with HTML syntax. - -
-
Name
-
Godzilla
-
Born
-
1952
-
Birthplace
-
Japan
-
Color
-
Green
-
- -#### Multiple description terms and values - -Term -: Brief description of Term - -Longer Term -: Longer description of Term, - possibly more than one line - -Term -: First description of Term, - possibly more than one line - -: Second description of Term, - possibly more than one line - -Term1 -Term2 -: Single description of Term1 and Term2, - possibly more than one line - -Term1 -Term2 -: First description of Term1 and Term2, - possibly more than one line - -: Second description of Term1 and Term2, - possibly more than one line - -### More code - -```python{% raw %} -def dump_args(func): - "This decorator dumps out the arguments passed to a function before calling it" - argnames = func.func_code.co_varnames[:func.func_code.co_argcount] - fname = func.func_name - def echo_func(*args,**kwargs): - print fname, ":", ', '.join( - '%s=%r' % entry - for entry in zip(argnames,args) + kwargs.items()) - return func(*args, **kwargs) - return echo_func - -@dump_args -def f1(a,b,c): - print a + b + c - -f1(1, 2, 3) - -def precondition(precondition, use_conditions=DEFAULT_ON): - return conditions(precondition, None, use_conditions) - -def postcondition(postcondition, use_conditions=DEFAULT_ON): - return conditions(None, postcondition, use_conditions) - -class conditions(object): - __slots__ = ('__precondition', '__postcondition') - - def __init__(self, pre, post, use_conditions=DEFAULT_ON): - if not use_conditions: - pre, post = None, None - - self.__precondition = pre - self.__postcondition = post -{% endraw %}``` - -``` -Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this. -``` - -### Mermaid Diagrams - -The following code is displayed as a diagram only when a `mermaid` key supplied in `_config.yml`. - -```mermaid -graph TD; - A-->B; - A-->C; - B-->D; - C-->D; -``` - -### Collapsed Section - -The following uses the [`
`](https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/organizing-information-with-collapsed-sections) tag to create a collapsed section. - -
-Shopping list (click me!) - -This is content inside a `
` dropdown. - -- [ ] Apples -- [ ] Oranges -- [ ] Milk - -
diff --git a/docs_old/layout/layout.md b/docs_old/layout/layout.md deleted file mode 100644 index 832cbb1..0000000 --- a/docs_old/layout/layout.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Layout -layout: default -nav_order: 4.5 -has_children: true ---- - -# Layout - -You specify the layout for a page in its [front matter]. Just the Docs has a `default` layout with a sidebar, used for almost all pages in the theme docs, and a `minimal` layout that omits the sidebar. -{: .fs-6 .fw-300 } - -## The layout concept - -See the [Jekyll docs page about layouts] for an explanation of the general idea of layouts and how to specify them. - -You can use [Jekyll's front matter defaults] to specify the same layout for many pages. - -## The `default` layout - -This page uses the default layout. - -It is a *responsive* layout: on medium and larger width displays, it displays a sidebar, including a navigation panel; on smaller width displays, the sidebar is automatically hidden under a button. - -Each child (and grandchild) page of a top-level page has so-called *breadcrumbs*: links to its parent (and grandparent) pages. It shows the breadcrumbs above the main content of the page. - -Each page that has child pages generally has a list of links to those pages (you can suppress it by `has_toc: false` in the front matter). It shows the list as a *table of contents* below the main content. - -## The `minimal` layout - -A child and grandchild page of this page use the minimal layout. This differs from the default layout by omitting the sidebar---and thereby also the navigation panel. To navigate between pages with the minimal layout, you can use the breadcrumbs and the tables of contents. - -## Selectively hiding or showing the sidebar - -[Jekyll's front matter defaults] can be used to apply the `minimal` layout for many pages. But there are also other variables that can control the page layout. In `_config.yml`, you can set `nav_enabled: false` to disable the sidebar navigation panel across the entire site. This can then be selectively enabled on a page-by-page basis by assigning the `nav_enabled: true` page [front matter] variable. For instance, this could be used to enable sidebar navigation on a home page while all other pages have sidebar navigation disabled. - -```yaml ---- -layout: default -title: Home -nav_enabled: true ---- - -``` - -## Other layouts - -Just the Docs has further layouts: `about`, `home`, `page`, and `post`. Currently, they are all based on the `default` layout. See the [Jekyll docs about inheritance] for how to customize them. - -[front matter]: https://jekyllrb.com/docs/front-matter/ "Jekyll docs about front matter" -[Jekyll docs page about layouts]: https://jekyllrb.com/docs/layouts/ "Jekyll docs about layouts" -[Jekyll's front matter defaults]: https://jekyllrb.com/docs/configuration/front-matter-defaults/ "Jekyll docs about front matter defaults" -[Jekyll docs about inheritance]: https://jekyllrb.com/docs/layouts/#inheritance "Jekyll docs about inheritance" diff --git a/docs_old/layout/minimal/default-child.md b/docs_old/layout/minimal/default-child.md deleted file mode 100644 index 3035580..0000000 --- a/docs_old/layout/minimal/default-child.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Default layout child page -layout: default -parent: A minimal layout page -grand_parent: Layout ---- - -This is a child page that uses the same minimal layout as its parent page. diff --git a/docs_old/layout/minimal/minimal-child.md b/docs_old/layout/minimal/minimal-child.md deleted file mode 100644 index 26bcff7..0000000 --- a/docs_old/layout/minimal/minimal-child.md +++ /dev/null @@ -1,8 +0,0 @@ ---- -title: Minimal layout child page -layout: minimal -parent: A minimal layout page -grand_parent: Layout ---- - -This is a child page that uses the same minimal layout as its parent page. diff --git a/docs_old/layout/minimal/minimal.md b/docs_old/layout/minimal/minimal.md deleted file mode 100644 index 1821d67..0000000 --- a/docs_old/layout/minimal/minimal.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -title: A minimal layout page -layout: minimal -parent: Layout -has_children: true ---- - -# A minimal layout page - -This page illustrates the built-in layout `minimal`. - -One of its child pages also uses the minimal layout; the other child pages uses the default layout. diff --git a/docs_old/minimal-test.md b/docs_old/minimal-test.md deleted file mode 100644 index aa754d3..0000000 --- a/docs_old/minimal-test.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -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. diff --git a/docs_old/navigation-structure.md b/docs_old/navigation-structure.md deleted file mode 100644 index 75519d8..0000000 --- a/docs_old/navigation-structure.md +++ /dev/null @@ -1,364 +0,0 @@ ---- -layout: default -title: Navigation Structure -nav_order: 5 ---- - -# Navigation Structure -{: .no_toc } - -
- - Table of contents - - {: .text-delta } -- TOC -{:toc} -
- ---- - -## Main navigation - -The main navigation for your Just the Docs site is on the left side of the page on 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 (ordering pages) -{: .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 (excluding pages) -{: .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 (parent pages) -{: .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 (child pages) -{: .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 (ordering child pages) -{: .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 (auto-generating Table of Contents) -{: .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 (children within children) -{: .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. - ---- - -## Grouping pages with collections - -Pages can also be grouped together by using Jekyll's and Just the Docs's [collections]({% link docs/configuration.md %}#document-collections) feature. In contrast to using [pages with children](#pages-with-children), pages grouped by collection are grouped by a shared header (the name of the collection) instead of a page. - -The `nav_fold` configuration option works for collection-grouped pages. For more information, please refer to the [collections documentation]({% link docs/configuration.md %}#document-collections). - -### Example (grouping by collection) -{: .no_toc } - -The following example sets up two collections, `collection-one` and `collection-two`: - -- any document placed within `_collection-1/` will be grouped under the `Collection One` header by default. Since `nav_fold` is set to `true`, the pages will be folded by default. -- any document placed within `_collection-2/` will be grouped under the `Collection Two` header by default. Since `nav_fold` is set to `false`, the pages will be expanded by default. - -```yaml -_config.yml: - collections: - collection-one: - permalink: "/:collection/:path/" - output: true - collection-two: - permalink: "/:collection/:path/" - output: true - just_the_docs: - collections: - collection-one: - name: Collection One - nav_fold: true - collection-two: - name: Collection Two - nav_fold: false -``` ---- - -## 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 (auxiliary links) -{: .no_toc } - -```yaml -# Aux links for the upper right navigation -aux_links: - "Just the Docs on GitHubsss": - - "//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 (external navigation links) -{: .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 - opens_in_new_tab: false # set to true to open this link in a new tab - defaults to false -``` - -### Opening external links in a new tab -{: .d-inline-block } - -New (unreleased) -{: .label .label-green } - -The external links are decorated by an icon, which distinguishes them from internal links. -You can suppress the icon by setting `hide_icon: true`. - -By default, external links are not opened in a new tab. However, this can be enabled by: - -1. setting `opens_in_new_tab: true` in the link's configuration object -2. setting the configuration option `nav_external_links_new_tab: true` in `_config.yml` - -When they conflict, `opens_in_new_tab` takes precedence. - ---- - -## 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 `
    ` 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 (in-page navigation with Table of Contents) -{: .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 `
    ` and `` 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 -
    - - Table of contents - - {: .text-delta } -1. TOC -{:toc} -
    -``` - -The result is shown at [the top of this page](#navigation-structure) (`{:toc}` can be used only once on each page). diff --git a/docs_old/search.md b/docs_old/search.md deleted file mode 100644 index f48ae45..0000000 --- a/docs_old/search.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -layout: default -title: Search -nav_order: 7 ---- - -# Search -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - -Just the Docs uses [lunr.js](https://lunrjs.com) to add a client-side search interface powered by a JSON index that Jekyll generates. -All search results are shown in an auto-complete style interface (there is no search results page). -By default, all generated HTML pages are indexed using the following data points: - -- Page title -- Page content -- Page URL - -## Enable search in configuration - -In your site's `_config.yml`, enable search: - -```yaml -# Enable or disable the site search -# Supports true (default) or false -search_enabled: true -``` - -### Search granularity - -Pages are split into sections that can be searched individually. -The sections are defined by the headings on the page. -Each section is displayed in a separate search result. - -```yaml -# Split pages into sections that can be searched individually -# Supports 1 - 6, default: 2 -search.heading_level: 2 -``` - -### Search previews - -A search result can contain previews that show where the search words are found in the specific section. - -```yaml -# Maximum amount of previews per search result -# Default: 3 -search.previews: 3 - -# Maximum amount of words to display before a matched word in the preview -# Default: 5 -search.preview_words_before: 5 - -# Maximum amount of words to display after a matched word in the preview -# Default: 10 -search.preview_words_after: 10 -``` - -### Search tokenizer - -The default is for hyphens to separate tokens in search terms: -`gem-based` is equivalent to `gem based`, matching either word. -To allow search for hyphenated words: - -```yaml -# Set the search token separator -# Default: /[\s\-/]+/ -# Example: enable support for hyphenated search words -search.tokenizer_separator: /[\s/]+/ -``` - -### Display URL in search results - -```yaml -# Display the relative url in search results -# Supports true (default) or false -search.rel_url: false -``` - -### Display search button - -The search button displays in the bottom right corner of the screen and triggers the search input when clicked. - -```yaml -# Enable or disable the search button that appears in the bottom right corner of every page -# Supports true or false (default) -search.button: true -``` - -### Focus search bar with a keyboard shortcut - -Just the Docs supports focusing the search bar input with a keyboard shortcut. After setting the `search.focus_shortcut_key` config item key, users who press Ctrl + `search.focus_shortcut_key` (or on macOS, Command + `search.focus_shortcut_key`) will focus the search bar. - -Note that this feature is **disabled by default**. `search.focus_shortcut_key` should be a [valid value from `KeyboardEvent.key`](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/key); this involves all ASCII alphanumeric values, as well as modifier keys. - -For example, - -```yaml -search: - focus_shortcut_key: 'k' -``` - -Will make Ctrl + K focus the search bar for Windows users (and Command + K on macOS). - -## Hiding pages from search - -Sometimes you might have a page that you don't want to be indexed for the search nor to show up in search results, e.g., a 404 page. -To exclude a page from search, add the `search_exclude: true` parameter to the page's YAML front matter: - -#### Example - -{: .no_toc } - -```yaml ---- -layout: default -title: Page not found -nav_exclude: true -search_exclude: true ---- - -``` - -## Generate search index when used as a gem - -If you use Just the Docs as a remote theme, you do not need the following steps. - -If you use the theme as a gem, you must initialize the search by running this `rake` command that comes with `just-the-docs`: - -```bash -$ bundle exec just-the-docs rake search:init -``` - -This command creates the `assets/js/zzzz-search-data.json` file that Jekyll uses to create your search index. -Alternatively, you can create the file manually with [this content]({{ site.github.repository_url }}/blob/main/assets/js/zzzz-search-data.json). - -## Custom content for search index -{: .d-inline-block } - -New (v0.4.0) -{: .label .label-green } - -Advanced -{: .label .label-yellow } - -By default, the search feature indexes a page's `.content`, `.title`, and *some* headers within the `.content`. Other data (e.g. front matter, files in `_data` and `assets`) is not indexed. Users can customize what is indexed. - -{: .warning } -> Customizing search indices is an advanced feature that requires Javascript and Liquid knowledge. - -1. When Just the Docs is a local or gem theme, ensure `assets/js/zzzz-search-data.json` is up-to-date with [Generate search index when used as a gem](#generate-search-index-when-used-as-a-gem). -2. Add a new file named `_includes/lunr/custom-data.json`. Insert custom Liquid code that reads your data (e.g. the page object at `include.page`) then generates custom Javascript fields that hold the custom data you want to index. Verify these fields in the generated `assets/js/search-data.json`. -3. Add a new file named `_includes/lunr/custom-index.js`. Insert custom Javascript code that reads your custom Javascript fields and inserts them into the search index. You may want to inspect `assets/js/just-the-docs.js` to better understand the code. - -#### Example - -This example adds front matter `usage` and `examples` fields to the search index. - -`_includes/lunr/custom-data.json` custom code reads the page `usage` and `examples` fields, normalizes the text, and writes the text to custom Javascript `myusage` and `myexamples` fields. Javascript fields are similar yet [not the same as JSON](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON#javascript_and_json_differences). `jsonify` will probably work for most scenarios. - -{% raw %} -```liquid -{%- capture newline %} -{% endcapture -%} -"myusage": {{ include.page.usage | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }}, -"myexamples": {{ include.page.examples | markdownify | replace:newline,' ' | strip_html | normalize_whitespace | strip | jsonify }}, -``` -{% endraw %} - -`_includes/lunr/custom-index.js` custom code is inserted into the Javascript loop of `assets/js/just-the-docs.js`. All custom Javascript fields are accessed as fields of `docs[i]` such as `docs[i].myusage`. Finally, append your custom fields on to the already existing `docs[i].content`. - -```javascript -const content_to_merge = [docs[i].content, docs[i].myusage, docs[i].myexamples]; -docs[i].content = content_to_merge.join(' '); -``` diff --git a/docs_old/ui-components/buttons.md b/docs_old/ui-components/buttons.md deleted file mode 100644 index c4180b3..0000000 --- a/docs_old/ui-components/buttons.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -layout: default -title: Buttons -parent: UI Components -nav_order: 2 ---- - -# Buttons -{: .no_toc } - -## Table of contents -{: .no_toc .text-delta } - -1. TOC -{:toc} - ---- - -## Basic button styles - -### Links that look like buttons - -
    -[Link button](https://just-the-docs.com){: .btn } - -[Link button](https://just-the-docs.com){: .btn .btn-purple } -[Link button](https://just-the-docs.com){: .btn .btn-blue } -[Link button](https://just-the-docs.com){: .btn .btn-green } - -[Link button](https://just-the-docs.com){: .btn .btn-outline } -
    -```markdown -[Link button](https://just-the-docs.com){: .btn } - -[Link button](https://just-the-docs.com){: .btn .btn-purple } -[Link button](https://just-the-docs.com){: .btn .btn-blue } -[Link button](https://just-the-docs.com){: .btn .btn-green } - -[Link button](https://just-the-docs.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: - -
    - -
    -```html - -``` - ---- - -## Using utilities with buttons - -### Button size - -Wrap the button in a container that uses the [font-size utility classes]() to scale buttons: - -
    - -[Big ass button](https://just-the-docs.com){: .btn } - - - -[Tiny ass button](https://just-the-docs.com){: .btn } - -
    -```markdown - -[Link button](https://just-the-docs.com){: .btn } - - - -[Tiny ass button](https://just-the-docs.com){: .btn } - -``` - -### Spacing between buttons - -Use the [margin utility classes]() to add spacing between two buttons in the same block. - -
    -[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 } -[Button](https://just-the-docs.com){: .btn .btn-blue } - -[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 } -[Button](https://just-the-docs.com){: .btn .btn-blue } -
    -```markdown -[Button with space](https://just-the-docs.com){: .btn .btn-purple .mr-2 } -[Button](https://just-the-docs.com){: .btn .btn-blue } - -[Button with more space](https://just-the-docs.com){: .btn .btn-green .mr-4 } -[Button](https://just-the-docs.com){: .btn .btn-blue } -``` diff --git a/docs_old/ui-components/callouts.md b/docs_old/ui-components/callouts.md deleted file mode 100644 index e0ea86f..0000000 --- a/docs_old/ui-components/callouts.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -layout: default -title: Callouts -parent: UI Components -nav_order: 7 ---- - -# 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 } ->
    -> {: .warning } -> A paragraph ->
    -``` - -{: .important } -> {: .opaque } ->
    -> {: .warning } -> A paragraph ->
    diff --git a/docs_old/ui-components/code.md b/docs_old/ui-components/code.md deleted file mode 100644 index b55e361..0000000 --- a/docs_old/ui-components/code.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -layout: default -title: Code -parent: UI Components -has_children: true -nav_order: 6 ---- - -# 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. - -
    -Lorem ipsum dolor sit amet, `` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. - -## Heading with `` in it. -{: .no_toc } -
    -```markdown -Lorem ipsum dolor sit amet, `` adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. - -## Heading with `` 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: - -
    -```js -// Javascript code with syntax highlighting. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l) - return true; -} -``` -
    -{% highlight markdown %} -```js -// Javascript code with syntax highlighting. -var fun = function lang(l) { - dateformat.i18n = require('./lang/' + l) - return true; -} -``` -{% endhighlight %} - -Syntax highlighting, line numbers, and HTML compression do not work together; **the combination of these features generates invalid HTML that renders incorrectly**. To learn more, see ["Code with line numbers"]({% link docs/ui-components/line-nos.md %}). - ---- - -## 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 `
    ` 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... - -
    - -
    - -[Link button](https://just-the-docs.com){: .btn } - -
    -```markdown -[Link button](https://just-the-docs.com){: .btn } -``` - -
    -{% highlight markdown %} -
    - -[Link button](https://just-the-docs.com){: .btn } - -
    -```markdown -[Link button](https://just-the-docs.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.org/config/configuration.html). 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 - -To load a local version of mermaid, also use the `path` key to specify the location of the library; e.g. - -```yaml -mermaid: - version: "10.1.0" - # for (v10+) - path: "/assets/js/mermaid.esm.min.mjs" - # for (=10`, this file is imported directly as an ESM module (rather than as a plain `