chore: now DocLink works without keys (#79)

Author: Sudrut

astro.config.mjs

@@ -10,7 +10,7 @@ import starlightHeadingBadges from "starlight-heading-badges";
 export default defineConfig({
   site: process.env.CPPDOC_SITE,
   base: process.env.CPPDOC_BASE,
-  trailingSlash: "never",
+  trailingSlash: "always",
   integrations: [
     starlight({
       title: "CppDoc",

src/components/DocLink.astro

@@ -1,25 +1,24 @@
 ---
-import { getLinkToKey } from "../lib/doc-index";
+import { isLinkMissing, normalizeLink } from "../lib/doc-link";
 
 interface Props {
-  src: string;
+  dest: string;
   section?: string;
 }
 
-const { src, section } = Astro.props;
-const rawLink = await getLinkToKey(src);
+const { dest, section } = Astro.props;
 
-const missing = rawLink === undefined;
-const link = rawLink ? rawLink + (section ? "#" + section : "") : "";
+const missing = await isLinkMissing(dest);
+const link = normalizeLink(dest) + (section ? "#" + section : "");
 ---
 
 {
   missing ? (
-    <span class="doc-link missing" title={`${src} (missing)`}>
+    <span class="doc-link missing" title={`${dest} (missing)`}>
       <slot />
     </span>
   ) : (
-    <a class="doc-link" href={link} title={src}>
+    <a class="doc-link" href={link} title={dest}>
       <slot />
     </a>
   )

src/components/NamedReq.astro

@@ -9,12 +9,12 @@ interface Props {
 }
 
 const { name, bold, displayName, nolink } = Astro.props;
-const src = `/cpp/named_req/${name}`;
+const dest = `/cpp/named_req/${name}`;
 
 const text = displayName ?? name;
 
 const As = nolink ? Fragment : DocLink;
-const asProps = nolink ? {} : { src };
+const asProps = nolink ? {} : { dest };
 ---
 
 <As {...asProps}>

src/components/header/Header.astro

@@ -11,13 +11,13 @@ export interface Props {
 
 const { lang, name, displayName, nolink } = Astro.props;
 const langPrefix = lang == "C" ? "/c" : "/cpp";
-const src = `${langPrefix}/library/headers/${name}`;
+const dest = `${langPrefix}/library/headers/${name}`;
 
 const extension = lang === "C" ? ".h" : "";
 const text = displayName ?? `<${name}${extension}>`;
 
 const As = nolink ? Fragment : DocLink;
-const asProps = nolink ? {} : { src };
+const asProps = nolink ? {} : { dest };
 ---
 
 <As {...asProps}>

src/content/docs/c/comment.mdx

@@ -14,21 +14,21 @@ Comments serve as a sort of in-code documentation. When inserted into a program,
 1) Often known as "C-style" or "multi-line" comments.
 2) Often known as "C++-style" or "single-line" comments.
 
-All comments are removed from the program at <DocLink src="/c/language/translation_phases">translation phase 3</DocLink> by replacing each comment with a single whitespace character.
+All comments are removed from the program at <DocLink dest="/c/language/translation_phases">translation phase 3</DocLink> by replacing each comment with a single whitespace character.
 
 ### C-style
 
 C-style comments are usually used to comment large blocks of text or small fragments of code; however, they can be used to comment single lines. To insert text as a C-style comment, simply surround the text with `/*` and `*/`. C-style comments tell the compiler to ignore all content between `/*` and `*/`. Although it is not part of the C standard, `/**` and `**/` are often used to indicate documentation blocks; this is legal because the second asterisk is simply treated as part of the comment.
 
-Except within a <DocLink src="/c/language/character_constant">character constant</DocLink>, a <DocLink src="/c/language/string_literal">string literal</DocLink>, or a comment, the characters `/*` introduce a comment. The contents of such a comment are examined only to identify multibyte characters and to find the characters `*/` that terminate the comment. C-style comments cannot be nested.
+Except within a <DocLink dest="/c/language/character_constant">character constant</DocLink>, a <DocLink dest="/c/language/string_literal">string literal</DocLink>, or a comment, the characters `/*` introduce a comment. The contents of such a comment are examined only to identify multibyte characters and to find the characters `*/` that terminate the comment. C-style comments cannot be nested.
 
 <RevisionBlock since="C99">
 
 ### C++-style
 
 C++-style comments are usually used to comment single lines of text or code; however, they can be placed together to form multi-line comments. To insert text as a C++-style comment, simply precede the text with `//` and follow the text with the new line character. C++-style comments tell the compiler to ignore all content between `//` and a new line.
 
-Except within a <DocLink src="/c/language/character_constant">character constant</DocLink>, a <DocLink src="/c/language/string_literal">string literal</DocLink>, or a comment, the characters `//` introduce a comment that includes all multibyte characters up to, but not including, the next new-line character. The contents of such a comment are examined only to identify multibyte characters and to find the new-line character that terminates the comment. C++-style comments can be nested:
+Except within a <DocLink dest="/c/language/character_constant">character constant</DocLink>, a <DocLink dest="/c/language/string_literal">string literal</DocLink>, or a comment, the characters `//` introduce a comment that includes all multibyte characters up to, but not including, the next new-line character. The contents of such a comment are examined only to identify multibyte characters and to find the new-line character that terminates the comment. C++-style comments can be nested:
 
 ```c
 //  y = f(x);   // invoke algorithm
@@ -53,7 +53,7 @@ A C++-style comment may appear within a C-style comment; this is a mechanism for
 
 ### Notes
 
-Because comments <DocLink src="/c/language/translation_phases">are removed</DocLink> before the preprocessor stage, a macro cannot be used to form a comment and an unterminated C-style comment doesn't spill over from an #include'd file.
+Because comments <DocLink dest="/c/language/translation_phases">are removed</DocLink> before the preprocessor stage, a macro cannot be used to form a comment and an unterminated C-style comment doesn't spill over from an #include'd file.
 
 ```c
 /* An attempt to use a macro to form a comment. */
@@ -151,6 +151,6 @@ Hello, again
 
 <DescList>
   <Desc>
-    <DocLink slot="item" src="/cpp/comments">C++ documentation</DocLink> for <span>Comments</span>
+    <DocLink slot="item" dest="/cpp/comments">C++ documentation</DocLink> for <span>Comments</span>
   </Desc>
 </DescList>

src/content/docs/c/language/basic_concepts.mdx

@@ -12,12 +12,12 @@ import DocLink from "@components/DocLink.astro";
 
 This section provides definitions for the specific terminology and the concepts used when describing the C programming language.
 
-A C program is a sequence of text files (typically header and source files) that contain <DocLink src="/c/language/declarations">declarations</DocLink>. They undergo <DocLink src="/c/language/translation_phases">translation</DocLink> to become an executable program, which is executed when the OS calls its <DocLink src="/c/language/main_function">main function</DocLink> (unless it is itself the OS or another *freestanding* program, in which case the entry point is implementation-defined).
+A C program is a sequence of text files (typically header and source files) that contain <DocLink dest="/c/language/declarations">declarations</DocLink>. They undergo <DocLink dest="/c/language/translation_phases">translation</DocLink> to become an executable program, which is executed when the OS calls its <DocLink dest="/c/language/main_function">main function</DocLink> (unless it is itself the OS or another *freestanding* program, in which case the entry point is implementation-defined).
 
-Certain words in a C program have special meaning, they are <DocLink src="/c/keyword">keywords</DocLink>. Others can be used as <DocLink src="/c/language/identifier">identifiers</DocLink>, which may be used to identify <DocLink src="/c/language/object">objects</DocLink>, <DocLink src="/c/language/functions">functions</DocLink>, <DocLink src="/c/language/struct">struct</DocLink>, <DocLink src="/c/language/union">union</DocLink>, or <DocLink src="/c/language/enum">enumeration</DocLink> tags, their members, <DocLink src="/c/language/typedef">typedef</DocLink> names, <DocLink src="/c/language/statements">labels</DocLink>, or  <DocLink src="/c/preprocessor/replace">macros</DocLink>.
+Certain words in a C program have special meaning, they are <DocLink dest="/c/keyword">keywords</DocLink>. Others can be used as <DocLink dest="/c/language/identifier">identifiers</DocLink>, which may be used to identify <DocLink dest="/c/language/object">objects</DocLink>, <DocLink dest="/c/language/functions">functions</DocLink>, <DocLink dest="/c/language/struct">struct</DocLink>, <DocLink dest="/c/language/union">union</DocLink>, or <DocLink dest="/c/language/enum">enumeration</DocLink> tags, their members, <DocLink dest="/c/language/typedef">typedef</DocLink> names, <DocLink dest="/c/language/statements">labels</DocLink>, or  <DocLink dest="/c/preprocessor/replace">macros</DocLink>.
 
-Each identifier (other than macro) is only valid within a part of the program called its <DocLink src="/c/language/scope">scope</DocLink> and belongs to one of four kinds of <DocLink src="/c/language/name_space">name spaces</DocLink>. Some identifiers have <DocLink src="/c/language/storage_duration">linkage</DocLink> which makes them refer to the same entities when they appear in different scopes or translation units.
+Each identifier (other than macro) is only valid within a part of the program called its <DocLink dest="/c/language/scope">scope</DocLink> and belongs to one of four kinds of <DocLink dest="/c/language/name_space">name spaces</DocLink>. Some identifiers have <DocLink dest="/c/language/storage_duration">linkage</DocLink> which makes them refer to the same entities when they appear in different scopes or translation units.
 
-Definitions of functions include sequences of <DocLink src="/c/language/statements">statements</DocLink> and <DocLink src="/c/language/declarations">declarations</DocLink>, some of which include <DocLink src="/c/language/expressions">expressions</DocLink>, which specify the computations to be performed by the program.
+Definitions of functions include sequences of <DocLink dest="/c/language/statements">statements</DocLink> and <DocLink dest="/c/language/declarations">declarations</DocLink>, some of which include <DocLink dest="/c/language/expressions">expressions</DocLink>, which specify the computations to be performed by the program.
 
-<DocLink src="/c/language/declarations">Declarations</DocLink> and <DocLink src="/c/language/expressions">expressions</DocLink> create, destroy, access, and manipulate <DocLink src="/c/language/object">objects</DocLink>. Each <DocLink src="/c/language/object">object</DocLink>, <DocLink src="/c/language/functions">function</DocLink>, and <DocLink src="/c/language/expressions">expression</DocLink> in C is associated with a <DocLink src="/c/language/type">type</DocLink>.
+<DocLink dest="/c/language/declarations">Declarations</DocLink> and <DocLink dest="/c/language/expressions">expressions</DocLink> create, destroy, access, and manipulate <DocLink dest="/c/language/object">objects</DocLink>. Each <DocLink dest="/c/language/object">object</DocLink>, <DocLink dest="/c/language/functions">function</DocLink>, and <DocLink dest="/c/language/expressions">expression</DocLink> in C is associated with a <DocLink dest="/c/language/type">type</DocLink>.