mirror of
https://github.com/snachodog/just-the-docs.git
synced 2025-04-21 18:42:23 -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.
3.5 KiB
3.5 KiB
layout, title, parent, nav_order
| layout | title | parent | nav_order |
|---|---|---|---|
| default | Typography | UI Components | 1 |
Typography
{: .no_toc }
Table of contents
{: .no_toc .text-delta }
- TOC {:toc}
Font stack
By default, Just the Docs uses a native system font stack for sans-serif fonts:
system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz {: .fs-5 .ls-10 .code-example }
For monospace type, like code snippets or the <pre> element, Just the Docs uses a native system font stack for monospace fonts:
"SFMono-Regular", Menlo, Consolas, Monospace
ABCDEFGHIJKLMNOPQRSTUVWXYZ abcdefghijklmnopqrstuvwxyz {: .fs-5 .ls-10 .text-mono .code-example }
Responsive type scale
Just the Docs uses a responsive type scale that shifts depending on the viewport size.
| Selector | Small screen size font-size |
Large screen size font-size |
|---|---|---|
h1, .text-alpha |
32px | 36px |
h2, .text-beta |
18px | 24px |
h3, .text-gamma |
16px | 18px |
h4, .text-delta |
14px | 16px |
h5, .text-epsilon |
16px | 18px |
h6, .text-zeta |
18px | 24px |
body |
14px | 16px |
Headings
Headings are rendered like this:
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Body text
Default body text is rendered like this:
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
```markdown
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
```
Inline elements
Text can be **bold**, _italic_, or ~~strikethrough~~.
```markdown
Text can be **bold**, _italic_, or ~~strikethrough~~.
---
## Typographic Utilities
There are a number of specific typographic CSS classes that allow you to override default styling for font size, font weight, line height, and capitalization.
[View typography utilities]({% link docs/utilities/typography.md %}){: .btn .btn-outline }