feat: add revision-specific content development guide

Lancern · Lancern · commit f6e57381f6e3 · 2025-12-01T01:24:11.000+08:00
diff --git a/README.md b/README.md
@@ -2,6 +2,33 @@
 
 An open documentation for the C/C++ programming languages and their standard libraries.
 
+> [!TIP]
+> Currently CppDoc community members are working hard on migrating [cppreference](https://en.cppreference.com/index.html) pages to CppDoc. You’re more than welcomed to join us if you want to help!
+
+## Quick Start
+
+Clone the project to your local:
+
+```bash
+git clone https://github.com/cppdoc-cc/cppdoc.git
+cd cppdoc
+```
+
+Start a development server:
+
+```bash
+npm i
+npm run dev
+```
+
+## Contributing
+
+CppDoc is an open documentation. Everyone is more than welcomed to contibute! Any kinds of contribution are greatly appreciated, including _but not limited_ to bug reports, bug fixes, feature requests, translations, new pages, and new documentation features.
+
+You can report a bug or request a new feature by [opening a new GitHub issue](https://github.com/cppdoc-cc/cppdoc/issues/new).
+
+If you have made some changes, you can [open a new GitHub pull request](https://github.com/cppdoc-cc/cppdoc/compare).
+
 ## License
 
 The content of the documentation is licensed under the [Creative Commons Attribution-ShareAlike 4.0 International license](./LICENSE.CC-BY-SA-4.0) and the [GNU Free Documentation License](./LICENSE.GFDL). The underlying source code used to process, format, and display that content is licensed under the [MIT license](./LICENSE.MIT).
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -3,7 +3,6 @@ import { defineConfig } from "astro/config";
 import starlight from "@astrojs/starlight";
 import starlightUtils from "@lorenzo_lewis/starlight-utils";
 import starlightAutoSidebar from "starlight-auto-sidebar";
-import starlightContextualMenu from "starlight-contextual-menu";
 import starlightHeadingBadges from "starlight-heading-badges";
 
 // https://astro.build/config
@@ -51,9 +50,6 @@ export default defineConfig({
       },
       plugins: [
         starlightAutoSidebar(),
-        starlightContextualMenu({
-          actions: ["chatgpt", "claude", "grok"],
-        }),
         starlightHeadingBadges(),
         starlightUtils({
           multiSidebar: {
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -17,7 +17,6 @@
     "nanostores": "^1.1.0",
     "sharp": "^0.34.2",
     "starlight-auto-sidebar": "0.1.3",
-    "starlight-contextual-menu": "0.1.5",
     "starlight-heading-badges": "0.6.1"
   },
   "devDependencies": {
diff --git a/src/assets/examples/development/guide/decl-doc-1.mdx b/src/assets/examples/development/guide/decl-doc-1.mdx
@@ -0,0 +1,11 @@
+import { Decl, DeclDoc } from "@components/decl-doc";
+
+<DeclDoc>
+  <Decl slot="decl">
+    ```cpp
+    int main() { /* body */ }
+    ```
+  </Decl>
+
+  A `main` function is the entry point of a program.
+</DeclDoc>
diff --git a/src/assets/examples/development/guide/decl-doc-2.mdx b/src/assets/examples/development/guide/decl-doc-2.mdx
@@ -0,0 +1,16 @@
+import { Decl, DeclDoc } from "@components/decl-doc";
+
+<DeclDoc>
+  <Decl slot="decl">
+    ```cpp
+    int main() { /* body */ }
+    ```
+  </Decl>
+  <Decl slot="decl">
+    ```cpp
+    int main(int argc, char *argv[]) { /* body */ }
+    ```
+  </Decl>
+
+  A `main` function is the entry point of a program.
+</DeclDoc>
diff --git a/src/assets/examples/development/guide/decl-doc-3.mdx b/src/assets/examples/development/guide/decl-doc-3.mdx
@@ -0,0 +1,24 @@
+import { Decl, DeclDoc } from "@components/decl-doc";
+import { RevisionBlock } from "@components/revision";
+
+<DeclDoc autorevSince="C++11">
+  <Decl slot="decl">
+    <RevisionBlock since="C++11" until="C++14" noborder>
+      ```cpp
+      template <typename T>
+      typename std::remove_reference<T>::type&& move(T&& t) noexcept;
+      ```
+    </RevisionBlock>
+  </Decl>
+  <Decl slot="decl">
+    <RevisionBlock since="C++14" noborder>
+      ```cpp
+      template <class T>
+      constexpr std::remove_reference_t<T>&& move(T&& t) noexcept;
+      ```
+    </RevisionBlock>
+  </Decl>
+
+  `std::move` is used to _indicate_ that an object `t` may be "moved from", i.
+  e. allowing the efficient transfer of resources from `t` to another object.
+</DeclDoc>
diff --git a/src/components/decl-doc/DeclDoc.astro b/src/components/decl-doc/DeclDoc.astro
@@ -39,6 +39,7 @@ const hasId = id !== undefined;
   }
 
   .decl-doc > .doc {
-    margin: 1em;
+    margin: 0;
+    padding: 1em;
   }
 </style>
diff --git a/src/components/revision/Revision.astro b/src/components/revision/Revision.astro
@@ -1,9 +1,9 @@
 ---
-import type { RevisionRange } from "@src/types";
 import RevisionTags from "./RevisionTags.astro";
 import { autoRev } from "./autorev";
+import type { RevisionInfo } from "./types";
 
-interface Props extends RevisionRange {
+interface Props extends RevisionInfo {
   noborder?: boolean;
 }
 
diff --git a/src/content/docs/c/language/basic/index.mdx b/src/content/docs/c/language/basic/index.mdx
@@ -1,6 +1,7 @@
 ---
 title: Overview
-order: 1
+sidebar:
+  order: 1
 cppdoc:
   keys: ["c.lang.basic"]
 ---
diff --git a/src/content/docs/c/library/headers/index.mdx b/src/content/docs/c/library/headers/index.mdx
@@ -1,6 +1,7 @@
 ---
 title: Overview
-order: 1
+sidebar:
+  order: 1
 cppdoc:
   keys: ["c.library.headers"]
 ---
diff --git a/src/content/docs/cpp/language/basic/index.mdx b/src/content/docs/cpp/language/basic/index.mdx
@@ -1,6 +1,7 @@
 ---
 title: Overview
-order: 1
+sidebar:
+  order: 1
 cppdoc:
   keys: ["cpp.lang.basic"]
 ---
diff --git a/src/content/docs/cpp/library/index.mdx b/src/content/docs/cpp/library/index.mdx
@@ -1,6 +1,7 @@
 ---
 title: Overview
-order: 1
+sidebar:
+  order: 1
 cppdoc:
   keys: ["cpp.library"]
 ---
diff --git a/src/content/docs/development/guide/_meta.yml b/src/content/docs/development/guide/_meta.yml
@@ -0,0 +1,2 @@
+label: Development Guideline
+order: 2
diff --git a/src/content/docs/development/guide/doc-everything.mdx b/src/content/docs/development/guide/doc-everything.mdx
@@ -0,0 +1,106 @@
+---
+title: Documenting Everything
+sidebar:
+  order: 3
+---
+
+import { Aside, Card, Code } from "@astrojs/starlight/components";
+import { Decl, DeclDoc } from "@components/decl-doc";
+import { RevisionBlock } from "@components/revision";
+
+This page contains guidelines for creating documents for various language or library entities.
+
+## Declaration
+
+### Basic Usage
+
+The `DeclDoc` component gives brief introduction to a C/C++ declaration.
+
+import declDocExample1 from "@src/assets/examples/development/guide/decl-doc-1.mdx?raw";
+
+<Code code={declDocExample1} lang="mdx" />
+
+<Card title="Preview">
+  <DeclDoc>
+    <Decl slot="decl">
+      ```cpp
+      int main() { /* body */ }
+      ```
+    </Decl>
+
+    A `main` function running independently of environment-provided arguments.
+  </DeclDoc>
+</Card>
+
+A `DeclDoc` component can contain multiple `Decl` as well:
+
+import declDocExample2 from "@src/assets/examples/development/guide/decl-doc-2.mdx?raw";
+
+<Code code={declDocExample2} lang="mdx" />
+
+<Card title="Preview">
+  <DeclDoc>
+    <Decl slot="decl">
+      ```cpp
+      int main() { /* body */ }
+      ```
+    </Decl>
+    <Decl slot="decl">
+      ```cpp
+      int main(int argc, char *argv[]) { /* body */ }
+      ```
+    </Decl>
+
+    A `main` function is the entry point of a program.
+  </DeclDoc>
+</Card>
+
+### Specifying Revisions
+
+You could specify revisions for each declaration with the `RevisionBlock` component:
+
+import declDocExample3 from "@src/assets/examples/development/guide/decl-doc-3.mdx?raw";
+
+<Code code={declDocExample3} lang="mdx" />
+
+<Card title="Preview">
+  <DeclDoc autorevSince="C++11">
+    <Decl slot="decl">
+      <RevisionBlock since="C++11" until="C++14" noborder>
+        ```cpp
+        template <typename T>
+        typename std::remove_reference<T>::type&& move(T&& t) noexcept;
+        ```
+      </RevisionBlock>
+    </Decl>
+    <Decl slot="decl">
+      <RevisionBlock since="C++14" noborder>
+        ```cpp
+        template <class T>
+        constexpr std::remove_reference_t<T>&& move(T&& t) noexcept;
+        ```
+      </RevisionBlock>
+    </Decl>
+
+    `std::move` is used to _indicate_ that an object `t` may be "moved from", i.
+    e. allowing the efficient transfer of resources from `t` to another object.
+  </DeclDoc>
+</Card>
+
+<Aside type="tip">
+  Don't forget the `autorevSince` attribute on the `DeclDoc` component! Presence of this attribute allows [autorev](./revision#autorev) to automatically hide the `DeclDoc` component when the user pins to a revision to which the `DeclDoc` content does not apply.
+</Aside>
+
+## Description List
+
+## Parameters
+
+## Links
+
+## Feature Test Macros
+
+## Defect Reports
+
+<Aside type="caution">
+  Not finished yet.
+</Aside>
diff --git a/src/content/docs/development/guide/index.mdx b/src/content/docs/development/guide/index.mdx
@@ -0,0 +1,7 @@
+---
+title: Overview
+sidebar:
+  order: 1
+---
+
+This section gives guidelines on developing CppDoc documentation pages. Click a specific topic on the left sidebar to continue.
diff --git a/src/content/docs/development/guide/new-component.mdx b/src/content/docs/development/guide/new-component.mdx
@@ -0,0 +1,11 @@
+---
+title: Adding New Components
+sidebar:
+  order: 6
+---
+
+import { Aside } from "@astrojs/starlight/components";
+
+<Aside type="caution">
+  Not finished yet.
+</Aside>
diff --git a/src/content/docs/development/guide/revision.mdx b/src/content/docs/development/guide/revision.mdx
diff --git a/src/content/docs/development/guide/translation.mdx b/src/content/docs/development/guide/translation.mdx
diff --git a/src/content/docs/development/guide/xref.mdx b/src/content/docs/development/guide/xref.mdx
diff --git a/src/content/docs/development/start.mdx b/src/content/docs/development/start.mdx

Original file line number	Diff line number	Diff line change
`@@ -39,6 +39,7 @@ const hasId = id !== undefined;`
`39`	`39`	`}`
`40`	`40`
`41`	`41`	`.decl-doc > .doc {`
`42`		`- margin: 1em;`
	`42`	`+ margin: 0;`
	`43`	`+ padding: 1em;`
`43`	`44`	`}`
`44`	`45`	`</style>`