mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-10 14:01:22 -06:00
d7e4a808b5
This PR is motivated from https://github.com/just-the-docs/just-the-docs/pull/1259#issuecomment-1655899503. It adds a new workflow (`CI / Validate HTML (3.1)`) that validates the output of `bundle exec jekyll build`. It does this with two separate tools: 1. The [`html5validator-action`](https://github.com/Cyb3r-Jak3/html5validator-action), which is a wrapper (Docker image + argument forwarding) around the [Nu HTML checker](https://github.com/validator/validator), which is what is used by the [W3C markup validation service](https://validator.w3.org/) 2. [`html-proofer`](https://github.com/gjtorikian/html-proofer), which performs auxiliary checks on the validity of script, image, and link *values*, but not the markup itself - note: prior versions of `html-proofer` did use nokogiri to also validate HTML, but the author has elected to remove that feature in versions 4+ I then fix a few issues that are flagged by these tools. I'll split this into, **changes affecting users**: - strictly incorrect: in `_layouts/minimal.html`, a `<div>` had duplicate `id`s. I've removed the incorrect one, which is related to... - semantically wrong (but not technically incorrect): in both `minimal` and `default` layouts, we had two `<div>` tags with `id="main-content-wrap"`. These don't do anything; the associated styling is with the *class* `main-content-wrap`. I've elected to remove these `id`s to avoid confusion and keep the layouts in sync; however, **this is technically a breaking change** - observe that `#main-content` is used for the "skip to main content" feature, which I missed in an earlier iteration of this PR **changes affecting only our documentation** - a broken link to mermaid docs (I've changed it to a valid one) - an incorrectly-specified `aux_link` to our own repository - various links that point to the bare URL `another-page`, which is clearly invalid; I've changed these to point to our homepage - an incorrect header link - various links to `http://example.com`, which I've changed to point to our homepage - an incorrect link to `@flyx`'s profile for the AsciiDoctor gist - a handful of (otherwise-valid) `http` links that should be `https`: the lunr docs, and patrick's personal website The commit history shows the Nu validator flagging issues in CI properly in commits [4128b23](4128b23ef2) and [3527220](35272203ba). ## relevant configuration - I exclude `github.com` URLs from external link checks with `html-proofer`. This is because GitHub does not like it when we ping too frequently, and rate limits us, which in turn provides many false positives. This is aligned with their documentation, which uses this ignore. - I've pinned the hash for the 3rd-party action that wraps the W3C markup validation service. This aligns with #1148, but means that we'll have to keep an eye on it for updates.
187 lines
6.1 KiB
YAML
187 lines
6.1 KiB
YAML
# Welcome to Jekyll!
|
|
#
|
|
# This config file is meant for settings that affect your whole site, values
|
|
# which you are expected to set up once and rarely edit after that. If you find
|
|
# yourself editing these this file very often, consider using Jekyll's data files
|
|
# feature for the data you need to update frequently.
|
|
#
|
|
# For technical reasons, this file is *NOT* reloaded automatically when you use
|
|
# 'jekyll serve'. If you change this file, please restart the server process.
|
|
|
|
# Site settings
|
|
# These are used to personalize your new site. If you look in the HTML files,
|
|
# you will see them accessed via {{ site.title }}, {{ site.github_repo }}, and so on.
|
|
# You can create any custom variable you would like, and they will be accessible
|
|
# in the templates via {{ site.myvariable }}.
|
|
title: Just the Docs
|
|
description: A Jekyll theme for documentation
|
|
baseurl: "" # the subpath of your site, e.g. /blog
|
|
url: "https://just-the-docs.com" # the base hostname & protocol for your site, e.g. http://example.com
|
|
repository: just-the-docs/just-the-docs # for github-metadata
|
|
|
|
permalink: pretty
|
|
|
|
exclude:
|
|
# from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml:
|
|
- .sass-cache/
|
|
- .jekyll-cache/
|
|
- gemfiles/
|
|
- Gemfile
|
|
- Gemfile.lock
|
|
- node_modules/
|
|
- vendor/bundle/
|
|
- vendor/cache/
|
|
- vendor/gems/
|
|
- vendor/ruby/
|
|
# specific to the theme website:
|
|
- bin/
|
|
- lib/
|
|
- "*.gemspec"
|
|
- "*.gem"
|
|
- LICENSE.txt
|
|
- package.json
|
|
- package-lock.json
|
|
- Rakefile
|
|
- README.md
|
|
- CODE_OF_CONDUCT.md
|
|
- docker-compose.yml
|
|
- Dockerfile
|
|
# theme test code
|
|
- fixtures/
|
|
|
|
# Set a path/url to a logo that will be displayed instead of the title
|
|
#logo: "/assets/images/just-the-docs.png"
|
|
|
|
# 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: 2
|
|
# Maximum amount of words to display before a matched word in the preview
|
|
# Default: 5
|
|
preview_words_before: 3
|
|
# Maximum amount of words to display after a matched word in the preview
|
|
# Default: 10
|
|
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
|
|
# Supports true or false (default)
|
|
button: false
|
|
|
|
# For copy button on code
|
|
enable_copy_code_button: true
|
|
|
|
# By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
|
|
mermaid:
|
|
# Version of mermaid library
|
|
# Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
|
|
version: "9.1.6"
|
|
# Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
|
|
# See also docs/ui-components/code
|
|
# To load mermaid from a local library, also use the `path` key to specify the location of the library; e.g.
|
|
# for (v10+):
|
|
# path: "/assets/js/mermaid.esm.min.mjs"
|
|
# for (<v10):
|
|
# path: "/assets/js/mermaid.min.js"
|
|
# Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
|
|
|
|
# Enable or disable heading anchors
|
|
heading_anchors: true
|
|
|
|
# Aux links for the upper right navigation
|
|
aux_links:
|
|
"Just the Docs on GitHub":
|
|
- "https://github.com/just-the-docs/just-the-docs"
|
|
|
|
# Makes Aux links open in a new tab. Default is false
|
|
aux_links_new_tab: false
|
|
|
|
# Sort order for navigation links
|
|
# nav_sort: case_insensitive # default, equivalent to nil
|
|
nav_sort: case_sensitive # Capital letters sorted before lowercase
|
|
|
|
# External navigation links
|
|
nav_external_links:
|
|
- title: Just the Docs on GitHub
|
|
url: https://github.com/just-the-docs/just-the-docs
|
|
|
|
# Footer content
|
|
# appears at the bottom of every page's main content
|
|
|
|
# Back to top link
|
|
back_to_top: true
|
|
back_to_top_text: "Back to top"
|
|
|
|
footer_content: "Copyright © 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> <a href=\"https://www.netlify.com/\">This site is powered by Netlify.</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
|
|
|
|
# Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
|
|
color_scheme: nil
|
|
|
|
callouts_level: quiet # or loud
|
|
callouts:
|
|
highlight:
|
|
color: yellow
|
|
important:
|
|
title: Important
|
|
color: blue
|
|
new:
|
|
title: New
|
|
color: green
|
|
note:
|
|
title: Note
|
|
color: purple
|
|
warning:
|
|
title: Warning
|
|
color: red
|
|
|
|
# Google Analytics Tracking (optional)
|
|
# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
|
|
# Note: the main Just the Docs site does *not* use Google Analytics.
|
|
# ga_tracking: UA-2709176-10,G-5FG1HLH3XQ
|
|
# ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
|
|
|
|
plugins:
|
|
- jekyll-seo-tag
|
|
- jekyll-github-metadata
|
|
- jekyll-include-cache
|
|
|
|
kramdown:
|
|
syntax_highlighter_opts:
|
|
block:
|
|
line_numbers: false
|
|
|
|
compress_html:
|
|
clippings: all
|
|
comments: all
|
|
endings: all
|
|
startings: []
|
|
blanklines: false
|
|
profile: false
|
|
# ignore:
|
|
# envs: all
|