docs: documentation style guide + tree-wide audit to standard#1060
Merged
Conversation
Adds a Documentation Style Guide (contributing/docs-style-guide) distilling Astro-grade conventions: readability, neutral voice (no we/us/let's), code-sample intros, Expressive Code diffs, the upgrade-guide breaking-changes format, headings, and EmDash specifics (sandboxed vs native, Atmosphere accounts, experimental surfaces, no messages.po in PRs). Audits and updates every other docs page against it. Excludes the pages in PR #1059 (plugin CLI/manifest/authoring docs). Also fixes real defects found during the audit: broken Astro frontmatter in three coming-from/wordpress code samples, two dead internal links (plugin-porting -> porting-plugins), an inconsistent field-type count, and competitor name-drops.
|
Contributor
Scope checkThis PR changes 1,269 lines across 54 files. Large PRs are harder to review and more likely to be closed without review. If this scope is intentional, no action needed. A maintainer will review it. If not, please consider splitting this into smaller PRs. See CONTRIBUTING.md for contribution guidelines. |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
emdash-perf-coordinator | 19d513d | May 16 2026, 01:50 PM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
emdash-i18n | 19d513d | May 16 2026, 01:50 PM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
docs | 19d513d | May 16 2026, 01:51 PM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
emdash-demo-cache | 19d513d | May 16 2026, 01:52 PM |
Deploying with
|
| Status | Name | Latest Commit | Updated (UTC) |
|---|---|---|---|
| ✅ Deployment successful! View logs |
emdash-playground | 19d513d | May 16 2026, 01:52 PM |
@emdash-cms/admin
@emdash-cms/auth
@emdash-cms/blocks
@emdash-cms/cloudflare
emdash
create-emdash
@emdash-cms/gutenberg-to-portable-text
@emdash-cms/x402
@emdash-cms/plugin-ai-moderation
@emdash-cms/plugin-atproto
@emdash-cms/plugin-audit-log
@emdash-cms/plugin-color
@emdash-cms/plugin-embeds
@emdash-cms/plugin-forms
@emdash-cms/plugin-webhook-notifier
commit: |
Contributor
There was a problem hiding this comment.
Pull request overview
This PR adds a new Documentation Style Guide to standardize tone, structure, and code-sample conventions across the EmDash documentation, and applies those conventions across a large portion of the docs tree. It also fixes a few documentation defects encountered during the audit (e.g., broken frontmatter and dead internal links).
Changes:
- Added
contributing/docs-style-guideand linked it in the docs sidebar. - Audited and updated many existing docs pages to match the new style guide (neutral voice, consistent headings, and clearer code-block introductions).
- Fixed some correctness issues discovered during the audit (frontmatter fences, internal link targets, and content consistency).
Reviewed changes
Copilot reviewed 54 out of 54 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/why-emdash.mdx | Title punctuation/style normalization. |
| docs/src/content/docs/themes/seed-files.mdx | Style-guide-aligned prose/code introductions across seed file reference. |
| docs/src/content/docs/themes/porting-wp-themes.mdx | Tone and instruction clarity updates; improved code-block introductions. |
| docs/src/content/docs/themes/overview.mdx | Reworked prose for neutrality/clarity and added clearer procedural intros. |
| docs/src/content/docs/themes/creating-themes.mdx | Refined guidance wording; added title= filenames and clearer intros. |
| docs/src/content/docs/reference/rest-api.mdx | Clarified auth/response format wording and improved structure. |
| docs/src/content/docs/reference/mcp-server.mdx | Added missing explanatory lead-in sentences for endpoints/JSON responses. |
| docs/src/content/docs/reference/hooks.mdx | Heading casing and added explicit table description intro. |
| docs/src/content/docs/reference/field-types.mdx | Added table intro and reworded sections; (note: field-type count accuracy needs correction). |
| docs/src/content/docs/reference/configuration.mdx | Improved explanations and added example lead-ins throughout configuration reference. |
| docs/src/content/docs/reference/cli.mdx | Improved instructional phrasing and added title= filenames for generated outputs. |
| docs/src/content/docs/reference/api.mdx | Added clearer example lead-ins and section intros; standardized headings. |
| docs/src/content/docs/plugins/overview.mdx | Terminology normalization (“formats” vs “flavours”). |
| docs/src/content/docs/plugins/installing.mdx | Improved prerequisites framing and headings; (note: config snippet correctness needs fixes). |
| docs/src/content/docs/plugins/field-kit.mdx | Added installation steps and better file-context titles; (note: config import path needs fix). |
| docs/src/content/docs/plugins/creating-native-plugins/your-first-native-plugin.mdx | Added explanatory lead-ins and standardized headings for native plugin guide. |
| docs/src/content/docs/plugins/creating-native-plugins/react-admin.mdx | Added missing explanatory sentences for examples; improved navigation/build sections. |
| docs/src/content/docs/plugins/creating-native-plugins/portable-text-components.mdx | Tone/clarity adjustment. |
| docs/src/content/docs/plugins/creating-native-plugins/page-fragments.mdx | Converted fragments into full-sentence example intros. |
| docs/src/content/docs/plugins/creating-native-plugins/distributing.mdx | Clarified packaging/publishing guidance; normalized headings. |
| docs/src/content/docs/migration/porting-plugins.mdx | Tone and concision improvements in AI-assisted porting aside. |
| docs/src/content/docs/migration/from-wordpress.mdx | Fixed internal link target for plugin porting guide. |
| docs/src/content/docs/migration/content-import.mdx | Improved clarity of endpoint descriptions and procedural wording; fixed internal links. |
| docs/src/content/docs/introduction.mdx | Added diagram lead-in; standardized “key concepts” intro language. |
| docs/src/content/docs/index.mdx | Normalized headings and improved quick-start code block intro. |
| docs/src/content/docs/guides/x402-payments.mdx | Added missing installation and configuration lead-in sentences. |
| docs/src/content/docs/guides/working-with-content.mdx | Added explicit lead-ins for API request examples. |
| docs/src/content/docs/guides/widgets.mdx | Added lead-ins for widget component examples. |
| docs/src/content/docs/guides/taxonomies.mdx | Fixed step numbering and added example lead-ins across API/examples. |
| docs/src/content/docs/guides/site-settings.mdx | Added lead-ins for component and API examples; clarified response wording. |
| docs/src/content/docs/guides/sections.mdx | Improved intros, added schema/seed file context, and clarified API examples. |
| docs/src/content/docs/guides/preview.mdx | Clarified example framing and standardized wording. |
| docs/src/content/docs/guides/media-library.mdx | Removed duplicated heading text; added code fence title and clearer API response language. |
| docs/src/content/docs/guides/internationalization.mdx | Added contextual lead-ins and clearer example framing. |
| docs/src/content/docs/guides/create-a-blog.mdx | Neutralized tone and added explicit “following example…” intros throughout. |
| docs/src/content/docs/guides/authentication.mdx | Added lead-ins for provider examples; normalized Cloudflare Access heading style. |
| docs/src/content/docs/guides/atmosphere-auth.mdx | Added missing setup lead-ins and improved clarity around login flow/metadata. |
| docs/src/content/docs/getting-started.mdx | Neutralized tone, improved example framing, and clarified env-var guidance. |
| docs/src/content/docs/docs-mcp.mdx | Clarified endpoint/public nature and improved manual setup instructions with titled config blocks. |
| docs/src/content/docs/deployment/storage.mdx | Added configuration/example lead-ins for S3/MinIO usage. |
| docs/src/content/docs/deployment/nodejs.mdx | Improved procedural phrasing and added missing command lead-ins. |
| docs/src/content/docs/deployment/database.mdx | Minor phrasing clarification around env-based selection. |
| docs/src/content/docs/deployment/cloudflare.mdx | Added lead-in and command sequence clarity for Access + secrets setup. |
| docs/src/content/docs/contributing/translating.mdx | Clarified policy wording and removed “we” voice. |
| docs/src/content/docs/contributing/index.mdx | Heading normalization. |
| docs/src/content/docs/contributing/docs-style-guide.mdx | New style guide defining documentation conventions and EmDash-specific terminology rules. |
| docs/src/content/docs/concepts/content-model.mdx | Standardized headings and improved example framing; simplified comparison section. |
| docs/src/content/docs/concepts/collections.mdx | Standardized headings and improved example framing; (note: field-type count accuracy needs correction). |
| docs/src/content/docs/concepts/architecture.mdx | Standardized headings, added diagram lead-in, and improved step formatting. |
| docs/src/content/docs/concepts/admin-panel.mdx | Standardized headings, added diagram lead-in, and improved list/steps formatting. |
| docs/src/content/docs/coming-from/wordpress.mdx | Fixed broken Astro frontmatter fences inside code samples; added lead-in sentences. |
| docs/src/content/docs/coming-from/astro.mdx | Added missing configuration/example lead-ins and tightened explanatory text. |
| docs/src/content/docs/coming-from/astro-for-wp-devs.mdx | Added lead-ins for examples and normalized headings. |
| docs/astro.config.mjs | Added sidebar entry for the new documentation style guide. |
Comments suppressed due to low confidence (2)
docs/src/content/docs/plugins/field-kit.mdx:28
- In an
astro.config.mjsexample, the integration should be imported fromemdash/astro(default export). Importingemdashfrom the rootemdashentrypoint is for runtime APIs and will not work as an Astro integration in config.
docs/src/content/docs/themes/seed-files.mdx:652 - The validation summary says slugs use "lowercase, underscores", but seed validation accepts multiple slug patterns (e.g. collection/field slugs use underscores, while other slugs like sections/terms use lowercase letters, numbers, and hyphens). Consider updating this bullet to reflect the actual rules enforced by
validateSeed()to avoid misleading readers.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| description: The writing, structure, and code-sample conventions for EmDash documentation. | ||
| --- | ||
|
|
||
| This guide defines how EmDash documentation is written. Contributions are edited to match it. You do not need to memorise it — reviewers and editors will help — but following it makes a contribution merge faster. |
Comment on lines
18
to
21
| 1. **Sandbox runner configured** — Marketplace plugins run in an isolated runtime, which requires the sandbox runner. The following configuration enables it: | ||
|
|
||
| ```typescript title="astro.config.mjs" | ||
| import { emdash } from "emdash/astro"; |
Comment on lines
+8
to
+12
| @@ -9,6 +9,8 @@ EmDash supports 14 field types for defining content schemas. Each type maps to a | |||
|
|
|||
| ## Overview | |||
|
|
|||
| The following table lists every field type and its SQLite column: | |||
Comment on lines
+53
to
56
| ## Field types | ||
|
|
||
| EmDash supports 15 field types that map to SQLite column types: | ||
| EmDash supports 14 field types that map to SQLite column types. | ||
|
|
Adds contributing/architecture (internals) and rewrites concepts/architecture, concepts/content-model, and concepts/admin-panel around what a reader decides and does. Relocates table layouts, the request path, code generation, admin internals, and the ImportSource extensibility API into the contributor doc rather than deleting them. Trims protocol/format internals from reference/mcp-server, migration/content-import, and guides/preview. Also corrects contributing/translating: AI-generated translations are accepted when a fluent speaker reviews every string and previews them in the running admin panel; only unsupervised machine output is rejected.
Removes 'database-first/schema as data' framing from user-facing pages
(it described an internal decision, not a user capability) and reframes
around what the reader does. The mechanism stays only in the contributor
architecture doc. Removes definition-by-negation ('no migration to write',
'no rebuild', 'without code') in favour of positive statements of what
happens. Keeps honest, specific comparison only on the evaluation and
'coming from' orientation pages.
Adds 'What to emphasise', 'Evergreen, not changelog', and a
definition-by-negation rule to the style guide, and reorders its own
'EmDash specifics' so it models the principle rather than ranking by
recency. Corrects the translating policy (supervised AI translations
are accepted).
Sweep against the AI-tropes reference across all in-scope pages. Mostly
definition-by-negation and straw-man self-definition still hiding in
intros and benefit cards ('no PHP', 'no API round-trips', 'without
rebuilds', 'no bundler, no manifest — just a regular npm package'),
restated as what the reader does or gets. Also: dramatic-pause em-dashes
split into sentences, prose pipeline arrows and a breadcrumb arrow
de-unicoded, a Kysely reference dropped from the introduction diagram,
and roadmap/changelog voice removed from the encryption-key and
auth-secret deployment notes. Definitional bold lists, appositive
em-dashes, UI breadcrumbs, code/diagram arrows, native plugin API code,
and honest comparison on evaluation/coming-from pages were preserved.
Verified each against packages/* source:
- getSections returns { items, nextCursor }, not Section[] (sections guide, api ref)
- removed fictional getSectionCategories / getSections({category}) from API ref
- getEmDashEntry options param, getSiteSetting("title"), isPreviewRequest/getPreviewToken take URL, search() returns { items } (api ref)
- content create flag is --draft (+ --locale/--translation-of), not --status (cli ref)
- r2/d1 import from @emdash-cms/cloudflare not emdash/astro|emdash/db; emdashLoader() takes no args; fonts list missing farsi (config ref)
- hook page:metadata link.rel allowlist + jsonld graph union (hooks ref)
- field type count 16 not 14; added url/repeater rows; corrected reserved field slugs (field-types ref, collections)
- REST: admin plugin paths, PUT not PATCH for collection/field/user updates, search response envelope, error codes (rest-api ref)
- MCP: 45 tools not 43, role requirements, error-envelope shape (mcp ref)
- media-library/architecture r2/local import paths; menus getMenus includes locale; widgets post.data.slug; admin-panel roles (no 'Developer' role)
Confirmed against source as non-existent (not planned, not drift-to-real):
- auth config object { selfSignup, session, cloudflareAccess }: emdash({auth})
takes an adapter (access() from @emdash-cms/cloudflare). Rewrote the
configuration + authentication auth sections to the real AuthDescriptor /
access() surface with accurate AccessConfig options; removed the invented
selfSignup/session config; pointed self-signup at the real provider allowlists.
- reference/api.mdx: removed Database functions / Repositories / Schema
registry sections (createDatabase is not a public export and there is no
public Kysely handle) and the searchCollection example (wrong signature,
needs a non-public db arg). Kept the verified-public search().
- guides/internationalization: removed the fictional 'emdash import wordpress
--locale --translation-of-locale' (no import CLI command/flags); point to
the real admin import flow + content create --locale --translation-of.
- configuration.mdx: dropped package.json emdash.description / emdash.preview
(not read by any code; label/seed/url are).
- installing.mdx: fix marketplace + config snippets — default import 'emdash from emdash/astro', add missing defineConfig import, sandboxRunner is a module specifier string not a boolean (verified: EmDashConfig.sandboxRunner?: string) - field-kit.mdx: integration imports from emdash/astro, not emdash - contributing/docs-style-guide.mdx: 'memorise' -> 'memorize' (US spelling) - themes/seed-files.mdx: correct the slug-validation summary (slug rules differ by type) instead of the misleading 'lowercase, underscores' Field-type count (field-types/collections, '14' -> '16') was already fixed in the earlier source-correctness pass; verified still correct.
…lass adapter postgres() is exported from emdash/db alongside sqlite/libsql (verified in source); only deployment/database + reference/configuration mentioned it. Corrected the SQLite-only framing in the pages that enumerate supported databases: - introduction: 'SQLite-compatible databases (D1, libSQL, local SQLite)' / cloud-portable bullets / aside / diagram - why-emdash: Cloud-Portable card + Cloudflare-deployment intro - concepts/architecture: diagram + 'what you configure' bullet - contributing/architecture: Kysely supported-dialect list - coming-from/astro: two comparison-table cells - deployment/nodejs: note libSQL/PostgreSQL also work, link to Database Options Diagram lines re-padded to preserve box alignment. Opinionated SQLite examples (getting-started, the nodejs walkthrough body) left as-is — they demonstrate one choice, they don't claim it's the only one.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What does this PR do?
Adds a Documentation Style Guide and brings the rest of the docs up to it.
New:
contributing/docs-style-guideDistils Astro-grade documentation conventions, adapted to EmDash:
title=filenames; Expressive Codedel/insdiffs instead of raw```diff.messages.po-not-in-PRs rule.Wired into the sidebar under Contributing.
Audited and updated ~52 other pages
Applied the guide across the whole docs tree except the pages in #1059 (plugin CLI / manifest / authoring docs, which were already rewritten there). Native-plugin docs were preserved (the native API is unchanged). Changes are surgical: code-sample intros, tone, headings, jargon, and
diff→Expressive Code.Defects fixed during the audit
coming-from/wordpresscode samples (a stray##had replaced the closing---)./migration/plugin-porting/→/migration/porting-plugins/).concepts/collectionssaid 15; the canonicalreference/field-typessays 14).Closes #
Type of change
Checklist
pnpm typecheckpasses — N/A, docs content onlypnpm lintpasses — N/A, docs content onlypnpm testpasses — N/A, docs content onlypnpm formathas been run — N/A, oxfmt does not format.mdx; frontmatter/JSX/fence/link checks done manually across all changed pagesmessages.potouchedAI-generated code disclosure
Screenshots / test output
Full
astro buildis blocked locally by a pre-existing Cloudflare env issue (AI_SEARCHbinding) unrelated to content. Validated instead across all 54 changed files: frontmatter present,<Aside>/<Steps>/<Tabs>balanced, code-fence parity, and every internal link resolves.Independent of, and does not overlap with, #1059.