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.
7.1 KiB
layout, title, nav_order
layout | title | nav_order |
---|---|---|
default | Markdown kitchen sink | 99 |
Preview dark color scheme
Text can be bold, italic, or strikethrough.
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
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
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
// Javascript code with syntax highlighting.
var fun = function lang(l) {
dateformat.i18n = require('./lang/' + l)
return true;
}
# Ruby code with syntax highlighting
GitHubPages::Dependencies.gems.each do |gem, version|
s.add_dependency(gem, "= #{version}")
end
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
- This is an ordered list following a header.
- This is an ordered list following a header.
- This is an ordered list following a header.
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.
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:
- Item one
- Item two
- Item three
- Item four
And an ordered list, continued:
- Item one
- Item two
Some text
{:style="counter-reset:none"}
- Item three
- Item four
And an ordered list starting from 42:
{:style="counter-reset:step-counter 41"}
- Item 42
- Item 43
- 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)
- level 2 item (ol)
- level 2 item (ol)
- level 3 item (ul)
- level 3 item (ul)
- level 1 item (ul)
- level 2 item (ol)
- level 2 item (ol)
- level 3 item (ul)
- level 3 item (ul)
- level 4 item (ol)
- 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
- 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
Large image
"Wroclaw University Library digitizing rare archival texts" by j_cadmus is marked with CC BY 2.0.
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
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 <details>
tag to create a collapsed section.
Shopping list (click me!)
This is content inside a <details>
dropdown.
- Apples
- Oranges
- Milk