Link Search Menu Expand Document

Configuration

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

Table of contents

  1. Top Banner
  2. Hero Background Image
  3. Search
  4. Heading anchor links
  5. Footer content
  6. Color scheme
  7. Google Analytics
  8. Document collections

View this site’s _config.yml file as an example.

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

Top Banner

# Choose whether to include the LSP and/or HiTS logos at the top of the page
banner_links:
  lsp: true
  hits: true

Hero Background Image

# Can specify an image to use as a background for hero blocks, as well as 
# a background for the site logo on pages without a hero.
hero_background: "/assets/images/hero_general-use.jpg"
# 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: 2
  previews: 2
  # Maximum amount of words to display before a matched word in the preview
  # Default: 3
  preview_words_before: 3
  # Maximum amount of words to display after a matched word in the preview
  # Default: 3
  preview_words_after: 3
  # 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 on desktop displays
  # Supports true or false (default)
  button: false
# 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
# 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-2021 Patrick Marsceill."

# License information
# Provide license information for the project. License data is provided in list
# format, so that multiple licenses may be included.
# NOTE: By default, description text will be "[site title] is licensed under the"
license:
  - description: 
    name: "MIT License"
    url: "https://github.com/pmarsceill/just-the-docs/blob/master/LICENSE.txt" 

# Footer logos
# Specify one or more linked logos to display.
footer_logos:
  - name: "Laboratory of Systems Pharmacology"
    image: "/assets/images/logo_lsp_white.svg"
    url: "https://hits.harvard.edu/the-program/laboratory-of-systems-pharmacology/about/"
  - name: "Harvard Medical School"  # the institution the logo represents
    image: "assets/images/logo_hms.svg"  # path to the logo file
    url: "https://hms.harvard.edu/"  # link to the institution (opens in new tab)

# 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/labsyspharm/just-the-docs-lsp" # 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.
  • 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 "light" (default), "blue", "bold", and "dark"
color_scheme: blue

See Customization for more information.

Google Analytics

# Google Analytics Tracking (optional)
# e.g, UA-1234567-89
ga_tracking: UA-5555555-55
ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true by default)

Document collections

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

For example, put all your documentation files in the _docs folder and create the docs collection:

# Define Jekyll collections
collections:
  # Define a collection named "docs", its documents reside in the "_docs" directory
  docs:
    permalink: "/:collection/:path/"
    output: true

just_the_docs:
  # Define which collections are used in just-the-docs
  collections:
    # Reference the "docs" collection
    docs:
      # Give the collection a name
      name: Documentation
      # Exclude the collection from the navigation
      # Supports true or false (default)
      nav_exclude: false
      # Exclude the collection from the search
      # Supports true or false (default)
      search_exclude: false

You can reference multiple collections. This creates categories in the navigation with the configured names.

collections:
  docs:
    permalink: "/:collection/:path/"
    output: true
  tutorials:
    permalink: "/:collection/:path/"
    output: true

just_the_docs:
  collections:
    docs:
      name: Documentation
    tutorials:
      name: Tutorials