Follow-up to #124, now that the pages are actually rendering on docs.internetcomputer.org. The sync is in developer-docs#397, publishing docs/ as the Frontends section.
Two small asks, both about the frontmatter we added in #125 rather than the prose.
1. overview.md: retitle
The frontmatter title is what the docs site renders as the page's H1 and as its sidebar entry, and "Static site overview" reads as a noun pile in both places. It is also the entry point of the section, so it is the one title a newcomer reads first.
---
-title: "Static site overview"
-description: "Deploy a static site to a certified assets canister with the static-site recipe"
+title: "Deploy a static site"
+description: "Deploy a built frontend, docs, or any folder of files to a canister that serves it over HTTP with response certification"
sidebar:
order: 1
---
The other seven titles read well as they are and we would not change them.
Worth noting where this lands: on our side the section is now grouped under a label we own ("Hosting a static site"), so this title is the page inside it. "Deploy a static site" is the action a reader takes there, and the page is already shaped that way (Get started, then configuration).
2. A naming convention for titles and descriptions
overview.md's description currently names both the recipe (static-site) and the canister (certified assets) in one sentence. A reader meeting this page for the first time then has three names for one thing, counting the legacy asset canister they may be migrating from.
The convention we have adopted on our side, and would like to keep consistent with yours:
| What |
Where it belongs |
| the goal, "a static site" |
prose, headings, titles, descriptions, navigation |
the recipe, @dfinity/static-site |
code blocks, and prose where the reader pins a version |
| the canister, certified-assets |
only where the canister's identity matters: its Candid interface, state-hash verification, contrasting it with another canister |
Nothing in the body needs changing for this today; it is a rule for the next page more than a cleanup of this one.
Why we are asking rather than overriding
These titles exist only because the docs site needs them: #125 stripped the H1s, so the title field is invisible when the pages are read on GitHub. That makes it tempting for us to just override them at sync time, and we would rather not: the pages would then be published under titles that do not appear anywhere in this repo, and the next person editing a page here would have no way to know what readers actually see. Keeping the titles yours keeps this repo the single source of truth.
No rush from our side. The sync is pinned to d9cb7df, so whenever this lands it comes through with the next sync.
Follow-up to #124, now that the pages are actually rendering on docs.internetcomputer.org. The sync is in developer-docs#397, publishing
docs/as the Frontends section.Two small asks, both about the frontmatter we added in #125 rather than the prose.
1.
overview.md: retitleThe frontmatter
titleis what the docs site renders as the page's H1 and as its sidebar entry, and "Static site overview" reads as a noun pile in both places. It is also the entry point of the section, so it is the one title a newcomer reads first.The other seven titles read well as they are and we would not change them.
Worth noting where this lands: on our side the section is now grouped under a label we own ("Hosting a static site"), so this title is the page inside it. "Deploy a static site" is the action a reader takes there, and the page is already shaped that way (
Get started, then configuration).2. A naming convention for titles and descriptions
overview.md's description currently names both the recipe (static-site) and the canister (certified assets) in one sentence. A reader meeting this page for the first time then has three names for one thing, counting the legacy asset canister they may be migrating from.The convention we have adopted on our side, and would like to keep consistent with yours:
@dfinity/static-siteNothing in the body needs changing for this today; it is a rule for the next page more than a cleanup of this one.
Why we are asking rather than overriding
These titles exist only because the docs site needs them: #125 stripped the H1s, so the
titlefield is invisible when the pages are read on GitHub. That makes it tempting for us to just override them at sync time, and we would rather not: the pages would then be published under titles that do not appear anywhere in this repo, and the next person editing a page here would have no way to know what readers actually see. Keeping the titles yours keeps this repo the single source of truth.No rush from our side. The sync is pinned to
d9cb7df, so whenever this lands it comes through with the next sync.