GRO-838 Adds support for _includes in docs src

_docs/latest/_includes/test-md.md

@@ -0,0 +1,3 @@
+## Included md file heading
+
+Included md file *markdown* (latest).

_docs/latest/embedding/authentication.md

@@ -16,6 +16,8 @@ latest: true
 
 # Modular embedding - authentication
 
+{% include {{ _includes }}/test-md.md %}
+
 {% include plans-blockquote.html feature="Authenticated embeds" sdk=true is_plural=true%}
 
 For using modular embedding with SSO in production, you'll need to set up authentication.

_docs/v0.63/_includes/test-html.html

@@ -0,0 +1 @@
+<p>v0.63-scoped <strong>partial</strong></p>

_docs/v0.63/embedding/authentication.md

@@ -14,6 +14,8 @@ redirect_from:
 
 # Modular embedding - authentication
 
+{% include {{ _includes }}/test-html.html %}
+
 {% include plans-blockquote.html feature="Authenticated embeds" sdk=true is_plural=true%}
 
 For using modular embedding with SSO in production, you'll need to set up authentication.

lib/frontmatter.js

@@ -13,7 +13,7 @@ function addFrontmatter(directory, frontmatter) {
     const stats = fs.statSync(filePath);
     if (stats.isDirectory()) {
       addFrontmatter(filePath, frontmatter);
-    } else if (canBeProcessedByFrontmatter(file)) {
+    } else if (canBeProcessedByFrontmatter(filePath)) {
       const fileContents = fs.readFileSync(filePath, "utf8");
       const { data, content } = matter(fileContents);
       // Merge the keys with the existing frontmatter.

lib/utils.js

@@ -7,6 +7,10 @@ const matter = require("gray-matter");
 const yaml = require("yamljs");
 
 function canBeProcessedByFrontmatter(filePath) {
+  if (filePath.includes("/_includes/")) {
+    return false;
+  }
+
   return path.extname(filePath) === ".md" || path.extname(filePath) === ".html"
 }
 

src/content.config.ts

@@ -5,7 +5,7 @@ import { DOCS_SRC_ROOT } from "./constants";
 
 const docs = defineCollection({
   loader: glob({
-    pattern: ["**/*.md", "!**/embedding/sdk/api/snippets/**"],
+    pattern: ["**/*.md", "!**/embedding/sdk/api/snippets/**", "!**/_includes/**"],
     base: DOCS_SRC_ROOT,
 
     // Preserves dots (.) in pathnames

src/lib/docs/collectRedirects.ts

@@ -5,7 +5,7 @@ import matter from "gray-matter";
 import { DOCS_SRC_ROOT } from "../../constants";
 import { resolveDocUrl } from "./resolveDoc";
 
-const EXCLUDE = ["**/embedding/sdk/api/snippets/**"];
+const EXCLUDE = ["**/embedding/sdk/api/snippets/**", "**/_includes/**"];
 
 type ScanTarget = { extension: "md" | "html"; stripExtension: boolean };
 

src/lib/docs/docsHtmlLoader.ts

@@ -21,7 +21,7 @@ export const docsHtmlLoader = (): Loader => ({
     const rootDir = fileURLToPath(config.root);
     const entries: string[] = glob.sync("**/*.html", {
       cwd: baseDir,
-      ignore: ["**/embedding/sdk/api/snippets/**"],
+      ignore: ["**/embedding/sdk/api/snippets/**", "**/_includes/**"],
     });
 
     for (const entry of entries) {

src/lib/liquid/liquidRenderer.ts

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { DOCS_SRC_ROOT } from "@/constants";
 import { buildVersionSupportTable } from "@/lib/docs/versionSupport";
 import { compose } from "@/lib/fn";
 import { Liquid, ParseError, TokenizationError } from "liquidjs";
@@ -41,7 +42,8 @@ const stripInvalidLiquidSpan = (
 };
 
 const ROOT = process.cwd();
-const INCLUDES_ROOT = path.join(ROOT, "_includes");
+const INCLUDES_ROOT_SITE = path.join(ROOT, "_includes");
+const INCLUDES_ROOT_DOCS = path.join(ROOT, DOCS_SRC_ROOT);
 
 const loadDataDir = (dir: string): Record<string, unknown> => {
   const data: Record<string, any> = {};
@@ -90,13 +92,15 @@ const collapseBlankLines = (html: string): string =>
 export const getLiquidRenderer = ({
   page,
   dirname,
+  _includes,
 }: {
   page: Record<string, unknown>;
   dirname: string;
+  _includes?: string;
 }) => {
   if (!liquidEngine) {
     liquidEngine = new Liquid({
-      root: [INCLUDES_ROOT],
+      root: [INCLUDES_ROOT_SITE, INCLUDES_ROOT_DOCS],
       jekyllInclude: true,
       jekyllWhere: true,
       strictVariables: false, // TODO: Would be nice to flip this to true
@@ -112,6 +116,7 @@ export const getLiquidRenderer = ({
     ...baseCtx,
     page,
     dirname,
+    _includes,
   };
 
   return {

src/pages/docs/[version]/[...slug].astro

@@ -36,9 +36,14 @@ export const getStaticPaths = async () => {
 const { version, slug = "" } = Astro.params;
 const { kind, doc } = Astro.props;
 const dirname = path.dirname(doc.filePath!);
+const _includes = `${version}/_includes`;
 
 // Process liquid first (e.g. control flow, includes, variables, etc)
-const lq = getLiquidRenderer({ page: doc.data, dirname });
+const lq = getLiquidRenderer({
+  page: doc.data,
+  dirname,
+  _includes,
+});
 const lqOutput = await lq.render(doc.body!, undefined, {
   maxSyntaxErrors: version === "latest" ? 0 : 3,
 });