Focus on writing good documentation

These pages are a copy of original documentation of Just the Docs from its Github location.

Just the Docs, the Jekyll template on which this website is based, gives your documentation a jumpstart with a responsive Jekyll theme that is easily customizable.

Getting started
Configuration
About Just the Docs

Getting started

Dependencies

Just the Docs is built for Jekyll, a static site generator. View the quick start guide for more information. Just the Docs requires no special plugins and can run on GitHub Pages’ standard Jekyll compiler. The Jekyll SEO Tag plugin is included by default (no need to run any special installation) to inject SEO and open graph metadata on docs pages. For information on how to configure SEO and open graph metadata visit the Jekyll SEO Tag usage guide.

Quick start: Use as a GitHub Pages remote theme

Add Just the Docs to your Jekyll site’s _config.yml as a remote theme
```
remote_theme: pmarsceill/just-the-docs
```
You must have GitHub Pages enabled on your repo, one or more Markdown files, and a _config.yml file. See an example repository

Local installation: Use the gem-based theme

Install the Ruby Gem

$ gem install just-the-docs

# .. or add it to your your Jekyll site’s Gemfile
gem "just-the-docs"

Add Just the Docs to your Jekyll site’s _config.yml
```
theme: "just-the-docs"
```
Optional: Initialize search data (creates search-data.json)
```
$ bundle exec just-the-docs rake search:init
```

Run you local Jekyll server

$ jekyll serve

# .. or if you're using a Gemfile (bundler)
$ bundle exec jekyll serve

Point your web browser to http://localhost:4000

If you’re hosting your site on GitHub Pages, set up GitHub Pages and Jekyll locally so that you can more easily work in your development environment.

Configuration

Just the Docs has some specific configuration parameters that can be defined in your Jekyll site’s _config.yml file.

View the template project site’s _config.yml file as an example.

Site logo

# Set a path/url to a logo that will be displayed instead of the title
logo: "/assets/images/just-the-docs.png"

Search

# 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

Aux links

# Aux links for the upper right navigation
aux_links:
  "Just the Docs on GitHub":
    - "//github.com/pmarsceill/just-the-docs"

# Makes Aux links open in a new tab. Default is false
aux_links_new_tab: false

Heading anchor links

# 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

Parent and sibling links

# Include links to parent and sibling pages when showing the automatic TOC
nav_next_prev: true
#
# The default arrows can be changed to other characters or words
# nav_prev_text: "&larr;"
# nav_up_text:   "&uarr;"
# nav_next_text: "&rarr;"

Footer content

# 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/pmarsceill/just-the-docs/tree/master/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/pmarsceill/just-the-docs" # the github URL for your repo
gh_edit_branch: "master" # 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.
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 master
gh_edit_source is the source directory that your project files are stored in (should be the same as site.source)
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

# Color scheme supports "dark", "light", and your custom schemes:
color_scheme: dark

See Customization for more information.

Toggle between two schemes

New

# color_scheme: nil                # default: light
# To add a button to switch all pages to a different scheme:
toggle_color_scheme: dark          # default: nil (no toggle button)
# To display the toggle button only on one page:
toggle_page_url: "/"               # default: nil (display on all pages)
# To toggle automatically when the system mode preference changes:
toggle_auto_mode: true             # default: nil (manual toggle)
# To set the button text for toggling and reverting:
# toggle_text_1: "&rarr; &#x26ab;" # default: "&rarr; Dark Mode"
# toggle_text_2: "&rarr; &#x26ab;" # default: "&rarr; Light Mode"

Callouts

To use this feature, you need to configure a color and (optionally) title for each kind of callout you want to use, e.g.:

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.¹ You can then style a paragraph as a warning callout like this:

{: .warning }
A paragraph...

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/custom.scss file:

$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.:

callouts:
  custom:
    color: pink
    opacity: 0.3

You can change the default opacity (0.2) for all callouts, e.g.:

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 for more information.

Document collections

By default, the navigation and search include normal pages. You can also use Jekyll collections which group documents semantically together.

For example, put all your test files in the _tests folder and create the tests collection:

# 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
      # 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.

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.

By default, the navigation panel always shows links to all the top-level pages in all collections. You can configure whether individual collections appear folded, e.g.:

just_the_docs:
  collections:
    tests:
      name: Tests
      nav_fold: true
    tutorials:
      name: Tutorials
      nav_fold: false

Clicking the expander mark next to the name of a folded collection reveals the links to its top-level pages. Visiting any page in a folded collection reveals those links, and hides the links for all other folded collections.

About Just the Docs

If you use the dark color scheme, this callout uses $red-300 for the background, and $red-000 for the title. ↩

↑ →