diff --git a/_assets/styles/_custom.scss b/_assets/styles/_custom.scss index 8a086d7d2..3f172d146 100644 --- a/_assets/styles/_custom.scss +++ b/_assets/styles/_custom.scss @@ -1,5 +1,11 @@ // Custom Styles +// The navbar is fixed, so an anchor lands behind it without this. The extra +// room keeps the target clear of the bar rather than flush against it. +html { + scroll-padding-top: calc(#{$navbar-height} + 1rem); +} + main { min-height: 100%; } diff --git a/_assets/styles/_docs.scss b/_assets/styles/_docs.scss new file mode 100644 index 000000000..abe00f8f6 --- /dev/null +++ b/_assets/styles/_docs.scss @@ -0,0 +1,358 @@ +@use 'sass:color'; + +// The docs index: what is written, and what is still open. + +// This page reads wider than the 48ch column the rest of the site uses, so it +// sets its own width and its own offset under the fixed navbar. Colours come +// from _sublime-theme.scss; $docs-muted is the tone _home.scss gives secondary +// copy, so the two pages read alike. + +$docs-wrap: 1200px; +$docs-gutter: clamp(1rem, 4vw, 3rem); +$docs-link: shade-color($primary, 25%); +$docs-primary-tint: tint-color($primary, 30%); +$docs-muted: #4b433c; +$docs-hairline: rgb(167 151 139 / 55%); + +// A pale wash with deep-shade text, so the chip clears AA at this size. +$docs-flag-bg: tint-color($quaternary, 88%); +$docs-flag-text: shade-color($quaternary, 25%); + +// Scoped to `main` to keep the resets off the navbar and footer, which are +// its siblings under the same body class. The padding replaces what +// `main > .container` gives the footer elsewhere. +.docs main { + padding-bottom: 104px; +} + +.docs main h1, +.docs main h2, +.docs main p, +.docs main dl, +.docs main dd, +.docs main ul { + margin: 0; +} + +.docs main ul { + padding: 0; + list-style: none; +} + +.docs main a { + color: $docs-link; +} + +.docs main :focus-visible { + outline: 2px solid $body-color; + outline-offset: 2px; +} + +.docs .wrap { + max-width: $docs-wrap; + padding-inline: $docs-gutter; + margin-inline: auto; +} + +/* --- Head -------------------------------------------------------------- */ + +// Ink, so it carries on from the navbar rather than leaving a pale band +// between the two. +.docs-head { + padding-top: calc(#{$navbar-height} + clamp(2rem, 5vw, 3.5rem)); + padding-bottom: clamp(2.25rem, 5vw, 3.5rem); + color: $body-bg; + background-color: $body-color; +} + +.docs-head :focus-visible { + outline-color: $body-bg; +} + +.docs-head-grid { + display: grid; + grid-template-columns: minmax(0, 1.4fr) minmax(0, 0.85fr); + gap: clamp(2rem, 5vw, 4rem); + align-items: start; +} + +// _custom.scss draws a rule after every h1. Beside a two-column grid it +// would stop at this column's edge, so it is off here. +.docs-title { + display: block; + font-size: clamp(1.875rem, 4.5vw, 2.75rem); + font-weight: 700; + line-height: 1.08; + letter-spacing: -0.02em; +} + +.docs-title::after { + content: none; +} + +.docs-lede { + max-width: 42ch; + margin-top: 1rem !important; + font-size: clamp(1rem, 1.6vw, 1.0625rem); + line-height: 1.6; + color: rgb(231 231 214 / 76%); +} + +/* --- Head: the invite ----------------------------------------------- + The shape `.join` has on the home page, carrying the handbook's own gap. + Both branches read the count the list further down is built from. +*/ + +.invite { + padding: 1.25rem 1.375rem; + background-color: rgb(231 231 214 / 4%); + border: 1px solid rgb(231 231 214 / 20%); +} + +.invite-eyebrow { + font-family: $font-family-monospace; + font-size: 0.6875rem; + color: $tertiary; + text-transform: uppercase; + letter-spacing: 0.08em; +} + +.invite-title { + display: flex; + flex-wrap: wrap; + gap: 0.5rem; + align-items: baseline; + margin-top: 0.625rem !important; + font-size: 1.1875rem; + font-weight: 700; + line-height: 1.3; + color: $body-bg; +} + +.invite-num { + font-family: $font-family-monospace; + font-size: clamp(2.25rem, 5vw, 2.75rem); + line-height: 0.9; + color: $docs-primary-tint; +} + +.invite-what { + margin-top: 0.75rem !important; + font-size: 0.9375rem; + line-height: 1.6; + color: rgb(231 231 214 / 70%); +} + +.invite-row { + padding-top: 0.875rem; + margin-top: 1rem !important; + border-top: 1px solid rgb(231 231 214 / 16%); +} + +// Links on the ink. `.docs main a` is (0,1,2), so a band rule needs `main` +// to reach them. +.docs main .docs-head a { + color: $body-bg; +} + +// The treatment `.join-row a` gives the home page's equivalent link. +.docs main .invite-row a { + font-family: $font-family-monospace; + font-weight: 700; + color: $body-bg; +} + +/* --- Shared section furniture ------------------------------------------ */ + +.docs .band { + padding-block: clamp(2.5rem, 6vw, 4rem); +} + +// The handbook is the substance of this page, so it sits on its own ground. +.docs .band-quiet { + background-color: color.mix($tertiary, $body-bg, 12%); + border-block: 1px solid $docs-hairline; +} + +.docs .section-head { + display: flex; + flex-wrap: wrap; + gap: 0.5rem 1rem; + align-items: baseline; + justify-content: space-between; + padding-bottom: 0.75rem; + border-bottom: 2px solid $body-color; +} + +.docs .section-title { + font-size: 1.125rem; + font-weight: 700; + letter-spacing: -0.01em; +} + +.docs .section-more { + font-family: $font-family-monospace; + font-size: 0.8125rem; +} + +.docs .section-count { + font-family: $font-family-monospace; + font-size: 0.8125rem; + color: $docs-muted; + text-transform: uppercase; + letter-spacing: 0.06em; +} + +/* --- Taking part -------------------------------------------------------- + A plain divided list: process and community links, the same kind of thing + as the home page's "How we work". +*/ + +.docs .part-list { + display: grid; + grid-template-columns: repeat(2, minmax(0, 1fr)); + gap: 0 clamp(1.5rem, 4vw, 3rem); + margin-top: 1.75rem !important; +} + +.docs .part-item { + padding-block: 1.375rem; + border-bottom: 1px solid $docs-hairline; +} + +.docs .part-name { + font-size: 1.0625rem; + font-weight: 700; +} + +.docs .part-what { + margin-top: 0.375rem !important; + font-size: 0.9375rem; + line-height: 1.6; + color: $docs-muted; +} + +/* --- The handbook ------------------------------------------------------- + Alphabetical, one row per rule, name and point side by side so the names + read as an index. The numeral uses `.area-num`'s recipe from the home page. +*/ + +.docs .handbook-lede { + max-width: 60ch; + margin-top: 1.25rem !important; + font-size: 0.9375rem; + line-height: 1.65; + color: $docs-muted; +} + +.docs .rule-list { + margin-top: 1.75rem !important; +} + +.docs .rule { + display: grid; + grid-template-columns: minmax(0, 19rem) minmax(0, 1fr); + gap: 0.25rem 2rem; + padding-block: 0.875rem; + border-bottom: 1px solid rgb(167 151 139 / 35%); +} + +.docs .rule:first-child { + border-top: 1px solid rgb(167 151 139 / 35%); +} + +// A grid, so the numeral keeps its own column and stays beside the first +// line of a title long enough to wrap. +.docs .rule-name { + display: grid; + grid-template-columns: 1.375rem minmax(0, 1fr); + gap: 0.5rem; + align-items: baseline; + font-size: 0.9375rem; + font-weight: 700; +} + +.docs .rule-num { + font-family: $font-family-monospace; + font-size: 0.75rem; + font-weight: 400; + color: $docs-link; +} + +.docs .rule-heading { + display: flex; + flex-wrap: wrap; + gap: 0.5rem; + align-items: baseline; +} + +.docs .rule-point { + font-size: 0.9375rem; + line-height: 1.6; +} + +// The chip carries the state in text, so it does not rest on colour alone. +.docs .rule-flag { + padding: 0.0625rem 0.4375rem; + font-family: $font-family-monospace; + font-size: 0.6875rem; + font-weight: 400; + color: $docs-flag-text; + text-transform: uppercase; + letter-spacing: 0.06em; + background-color: $docs-flag-bg; +} + +.docs .handbook-gap { + max-width: 60ch; + margin-top: 1.5rem !important; + font-size: 0.9375rem; + line-height: 1.65; + color: $docs-muted; +} + +/* --- Not here yet -------------------------------------------------------- + Quieter than the sections above: a heading at their size would promise a + third pillar the page does not have. +*/ + +.docs .band-tail { + padding-block: clamp(1.5rem, 3vw, 2rem); +} + +.docs .tail-title { + font-family: $font-family-monospace; + font-size: 0.75rem; + font-weight: 700; + color: $docs-muted; + text-transform: uppercase; + letter-spacing: 0.08em; +} + +.docs .tail-what { + max-width: 60ch; + margin-top: 0.625rem !important; + font-size: 0.9375rem; + line-height: 1.65; + color: $docs-muted; +} + +/* --- Narrow -------------------------------------------------------------- */ + +@media (width < 960px) { + .docs-head-grid { + grid-template-columns: minmax(0, 1fr); + } +} + +@media (width < 760px) { + .docs .part-list { + grid-template-columns: minmax(0, 1fr); + } + + // The name column stops earning its width once the point beside it wraps. + .docs .rule { + grid-template-columns: minmax(0, 1fr); + gap: 0.375rem; + } +} diff --git a/_assets/styles/_home.scss b/_assets/styles/_home.scss index 492b2ee26..066da7382 100644 --- a/_assets/styles/_home.scss +++ b/_assets/styles/_home.scss @@ -270,7 +270,13 @@ color: rgb(231 231 214 / 70%); } -.join-row a { +// Links on the ink. `.home main a` is (0,1,2), so a band rule needs `main` +// to reach them. +.home main .masthead a { + color: var(--parchment); +} + +.home main .join-row a { font-family: var(--mono); font-weight: 700; color: var(--parchment); @@ -282,7 +288,8 @@ color: rgb(231 231 214 / 58%); } -.join-coc a { +// Same weight as the rule above it, so this stays below it in the file. +.home main .join-coc a { color: rgb(231 231 214 / 82%); } diff --git a/_assets/styles/main.scss b/_assets/styles/main.scss index 820029fcd..dcb19855f 100644 --- a/_assets/styles/main.scss +++ b/_assets/styles/main.scss @@ -16,6 +16,7 @@ @import '../../node_modules/bootstrap/scss/nav'; @import '../../node_modules/bootstrap/scss/navbar'; @import '../../node_modules/bootstrap/scss/pagination'; +@import 'docs'; @import 'error'; @import 'home'; @import 'nav'; diff --git a/_includes/head.liquid b/_includes/head.liquid index c2c99f717..95756fbbe 100644 --- a/_includes/head.liquid +++ b/_includes/head.liquid @@ -14,7 +14,7 @@ > {% if status == 'unpublished' %} diff --git a/_layouts/docs.liquid b/_layouts/docs.liquid index f302652c0..48b01246c 100644 --- a/_layouts/docs.liquid +++ b/_layouts/docs.liquid @@ -9,7 +9,7 @@ body_classes: {% if editable != false %}
Edit
diff --git a/build/tasks/compile/siteify-health-files.mts b/build/tasks/compile/siteify-health-files.mts index c9b5f4c71..7e3701e29 100644 --- a/build/tasks/compile/siteify-health-files.mts +++ b/build/tasks/compile/siteify-health-files.mts @@ -114,18 +114,28 @@ for (const value of healthFiles) { case 'CODE_OF_CONDUCT.md': siteifyFile(value, 'collections/_docs', { title: 'OpenINF Code of Conduct', + description: + 'Respect people, their identities, their culture, and their work. ' + + 'Listen before responding.', + order: 2, editable: false, }); break; case 'CONTRIBUTING.md': siteifyFile(value, 'collections/_docs', { title: 'Contributing to OpenINF', + description: + 'How issues get claimed, what makes a pull request easy to merge, ' + + 'and the sign-off every contribution carries.', + order: 1, permalink: '/docs/dev/internals/contributing/', }); break; case 'SECURITY.md': { siteifyFile(value, 'collections/_docs', { title: 'OpenINF Security Policies', + description: 'How to report a vulnerability privately.', + order: 4, permalink: '/docs/dev/internals/security/', }); break; @@ -133,6 +143,8 @@ for (const value of healthFiles) { case 'SUPPORT.md': siteifyFile(value, 'collections/_docs', { title: 'Support • Frequently Asked Questions', + description: 'Where to ask, in the order worth trying.', + order: 3, permalink: '/docs/dev/faq/support/', }); break; diff --git a/collections/_docs/code-of-conduct.md b/collections/_docs/code-of-conduct.md index 56b8ce0c2..15f9c155c 100644 --- a/collections/_docs/code-of-conduct.md +++ b/collections/_docs/code-of-conduct.md @@ -2,6 +2,10 @@ title: OpenINF Code of Conduct permalink: /docs/code-of-conduct/ note: This file is autogenerated. Edit CODE_OF_CONDUCT.md instead. +description: >- + Respect people, their identities, their culture, and their work. Listen before + responding. +order: 2 editable: false --- diff --git a/collections/_docs/contributing.md b/collections/_docs/contributing.md index 0849b20fb..efca54e02 100644 --- a/collections/_docs/contributing.md +++ b/collections/_docs/contributing.md @@ -2,6 +2,10 @@ title: Contributing to OpenINF permalink: /docs/dev/internals/contributing/ note: This file is autogenerated. Edit CONTRIBUTING.md instead. +description: >- + How issues get claimed, what makes a pull request easy to merge, and the + sign-off every contribution carries. +order: 1 --- Want to contribute? Great! First, read this document, which is a set of diff --git a/collections/_docs/handbook/style/capitalization.md b/collections/_docs/handbook/style/capitalization.md index e243bf858..0a5d60fff 100644 --- a/collections/_docs/handbook/style/capitalization.md +++ b/collections/_docs/handbook/style/capitalization.md @@ -1,6 +1,7 @@ --- title: Capitalization key_point: When to capitalize, and when to leave a word lowercase. +stub: true --- > [!NOTE]\ diff --git a/collections/_docs/handbook/style/code-in-text.md b/collections/_docs/handbook/style/code-in-text.md index 4511d7d90..3f9268546 100644 --- a/collections/_docs/handbook/style/code-in-text.md +++ b/collections/_docs/handbook/style/code-in-text.md @@ -1,6 +1,7 @@ --- title: Code in Text key_point: What to set in code font, and how to explain placeholders. +stub: true --- > [!NOTE]\ diff --git a/collections/_docs/handbook/style/code-samples.md b/collections/_docs/handbook/style/code-samples.md index 5c5070dd6..d4b0449dc 100644 --- a/collections/_docs/handbook/style/code-samples.md +++ b/collections/_docs/handbook/style/code-samples.md @@ -1,6 +1,7 @@ --- title: Code Samples key_point: How to introduce and present a code sample. +stub: true --- > [!NOTE]\ diff --git a/collections/_docs/handbook/style/dashes.md b/collections/_docs/handbook/style/dashes.md index fc21dd634..3cb6664bf 100644 --- a/collections/_docs/handbook/style/dashes.md +++ b/collections/_docs/handbook/style/dashes.md @@ -1,6 +1,7 @@ --- title: Dashes key_point: Which dash to use, and how it differs from a colon. +stub: true --- > [!NOTE]\ diff --git a/collections/_docs/handbook/style/lists.md b/collections/_docs/handbook/style/lists.md index 6e6fd0f75..2817ff974 100644 --- a/collections/_docs/handbook/style/lists.md +++ b/collections/_docs/handbook/style/lists.md @@ -1,6 +1,7 @@ --- title: Lists key_point: How to introduce and punctuate lists. +stub: true --- > [!NOTE]\ diff --git a/collections/_docs/handbook/style/people-person-first-language.md b/collections/_docs/handbook/style/people-person-first-language.md index bd88d4ad2..536c80c82 100644 --- a/collections/_docs/handbook/style/people-person-first-language.md +++ b/collections/_docs/handbook/style/people-person-first-language.md @@ -1,7 +1,15 @@ --- title: Prefer People/Person-First Language When Appropriate +key_point: + Follow the community's own preference between person-first and identity-first + language. +stub: true --- +> [!NOTE]\ +> This page is a placeholder. The rule below stands; the guidance that would +> follow it is yet to be written. + As linguistic prescription: prefer person-first language when the community prefers referring to themselves as person-first. diff --git a/collections/_docs/security.md b/collections/_docs/security.md index da68bc48b..8fbb6784d 100644 --- a/collections/_docs/security.md +++ b/collections/_docs/security.md @@ -2,6 +2,8 @@ title: OpenINF Security Policies permalink: /docs/dev/internals/security/ note: This file is autogenerated. Edit SECURITY.md instead. +description: How to report a vulnerability privately. +order: 4 --- The OpenINF SDK team, now benefitting from [dual Maintainership][], takes the diff --git a/collections/_docs/support.md b/collections/_docs/support.md index c8b4cbbb7..869b33fb5 100644 --- a/collections/_docs/support.md +++ b/collections/_docs/support.md @@ -2,6 +2,8 @@ title: Support • Frequently Asked Questions permalink: /docs/dev/faq/support/ note: This file is autogenerated. Edit SUPPORT.md instead. +description: Where to ask, in the order worth trying. +order: 3 --- Having trouble? Please consult these official resources in order of appearance. diff --git a/collections/_pages/docs.html b/collections/_pages/docs.html index 418d46442..a5eaae3c2 100644 --- a/collections/_pages/docs.html +++ b/collections/_pages/docs.html @@ -1,60 +1,150 @@ --- title: Docs -body_classes: - - docs +layout: default permalink: /docs/ -custom_css: +description: + How to take part in OpenINF, and the house style the work is written in. +body_classes: - docs +eleventyImport: + collections: ['handbook', 'communityDocs'] --- -

- Lorem ipsum odor amet, consectetuer adipiscing elit. Leo vestibulum sagittis - ornare ante himenaeos integer urna. Etiam ullamcorper malesuada nisl tortor - ligula nulla habitasse hendrerit porta. Integer elit facilisi lacus; - adipiscing rutrum metus praesent. Dapibus montes convallis sed blandit - pharetra, tortor tellus commodo. Dis augue quisque et, ante aenean nisl. - Habitasse morbi interdum leo netus finibus ad maximus dignissim sociosqu? - Ullamcorper augue facilisi sapien class quam; eget commodo quisque. Porta - ligula porttitor cubilia nulla sem at posuere praesent et. Ex morbi curabitur - nisi consequat natoque. -

- -

- Venenatis efficitur ullamcorper cubilia; gravida fermentum placerat. Eu - suscipit accumsan lacus; orci hac posuere nisi netus per. Fames fames - porttitor inceptos sit congue placerat mollis egestas ornare. Eros odio semper - maecenas habitasse senectus arcu. Cubilia nostra rhoncus aliquam viverra - mollis interdum? Auctor velit mus et ullamcorper ligula phasellus. Himenaeos - fringilla tempor porta sem pharetra. Adipiscing cras laoreet hac adipiscing - cras integer at mus orci. -

- -

- Tortor sociosqu purus adipiscing lectus lacus lacus libero nisl. Primis proin - vehicula sapien massa, commodo sociosqu massa quam. Tempus non ornare ad - euismod maximus, tincidunt eu augue. Sodales nostra habitant himenaeos cubilia - mauris nec donec in. Nisi dictum risus rhoncus convallis pharetra commodo - porta cubilia. Aa eleifend sagittis dolor duis. Venenatis dolor ornare felis - mus finibus interdum sagittis. Egestas semper dictum risus pellentesque - litora? Potenti ac augue morbi natoque sem nam elementum vel. -

- -

- Eu gravida aptent laoreet bibendum vulputate aliquam ad massa maximus. Ac - mauris blandit fermentum nibh integer vehicula. Sapien turpis per tempus - hendrerit fusce nascetur egestas risus. Interdum fames pretium; viverra - parturient elit dui. Odio praesent parturient eu odio potenti, ad hac ad. Sem - ultrices neque donec a nullam nibh! Malesuada primis nec urna cras netus elit - litora elementum eu. Hac vivamus ultrices ridiculus; dictum magnis donec enim. - Cubilia fermentum in condimentum torquent integer iaculis. Arcu nulla lobortis - massa tempus metus nullam. -

- -

- Placerat venenatis nullam consectetur orci nunc mus. Penatibus nibh ornare, - lobortis quam et dui inceptos nec. Donec litora id quis cras montes. - Condimentum tortor vestibulum id hendrerit lectus cubilia eros pretium sit. - Nullam odio netus nostra integer integer? Phasellus sociosqu morbi consequat - cubilia urna erat velit dis ad. Arcu tincidunt condimentum pellentesque - dapibus sagittis magnis suspendisse dignissim urna. Mus duis non vitae mus - libero bibendum. -

+{%- assign handbook_total = collections.handbook | size -%} +{%- assign written = collections.handbook + | where_exp: 'doc', 'doc.data.stub != true' +-%} +{%- assign written_count = written | size -%} +{%- assign open_count = handbook_total | minus: written_count -%} +{%- assign rule_word = 'rules' -%} +{%- if open_count == 1 -%} + {%- assign rule_word = 'rule' -%} +{%- endif -%} +
+ +
+
+
+

Docs

+

+ Two kinds of writing live here: how to take part in the work, and how + the work gets written down. +

+
+ + + +
+
+ + +
+
+
+

Taking part

+ Vision +
+ +
    + {%- for doc in collections.communityDocs %} +
  • +

    + {{ doc.data.title }} +

    +

    {{ doc.data.description }}

    +
    • + {%- endfor %} +
+
+
+ + +
+
+
+

The style handbook

+

+ {{ written_count }} of {{ handbook_total }} written +

+
+ +

+ The house style our documentation and commit messages follow, one rule + to a page. Each rule is stated below, so you can find the one you need. +

+ +
+ {%- for doc in collections.handbook %} +
+
+ + + {{ doc.data.title }} + {%- if doc.data.stub %} + Unwritten + {%- endif %} + +
+
{{ doc.data.key_point }}
+
+ {%- endfor %} +
+ + {%- if open_count > 0 %} +

+ The rules marked unwritten have their line here but no page yet. Any + one of them is a contained piece of work. + How to contribute. +

+ {%- endif %} +
+
+ + +
+
+

Not here yet

+

+ The OpenINF SDK arrives in Q4 2026, and its reference documentation + arrives with it. + Progress shows up in the news. +

+
+
+
diff --git a/collections/_pages/home.html b/collections/_pages/home.html index f8c0cfee5..36ac03bb3 100644 --- a/collections/_pages/home.html +++ b/collections/_pages/home.html @@ -251,9 +251,8 @@

How we work

  • -

    - Style handbook + Style handbook

    The house style our documentation and commit messages follow. diff --git a/eleventy.config.mjs b/eleventy.config.mjs index 8c0057c55..762a46180 100644 --- a/eleventy.config.mjs +++ b/eleventy.config.mjs @@ -129,6 +129,22 @@ export default async function (eleventyConfig) { ); }); + // The two groups the index at /docs/ shows. The handbook is alphabetical, + // being reference; the community docs follow their `order`, and a doc + // without one stays off the index. + eleventyConfig.addCollection('handbook', (collectionApi) => { + return collectionApi + .getFilteredByGlob('collections/_docs/handbook/**/*.md') + .sort((a, b) => a.data.title.localeCompare(b.data.title)); + }); + + eleventyConfig.addCollection('communityDocs', (collectionApi) => { + return collectionApi + .getFilteredByGlob('collections/_docs/*.md') + .filter((doc) => typeof doc.data.order === 'number') + .sort((a, b) => a.data.order - b.data.order); + }); + eleventyConfig.addPlugin(EleventyI18nPlugin, { // Any valid BCP 47-compatible language tag is supported. defaultLanguage: 'en', // required