Normalized paths (#12)

* normalized paths

* run-all package added

* added postcss.config.js if package which uses this template still use lower version of tailwind

* removed postcss and updated vitest dependencies

* small update with helper functions in content-collections.ts

* restored previous helper functions

Author: abrulic

README.md

@@ -97,12 +97,13 @@ pnpm install
 ```
 3. Read through the README.md files in the project to understand our decisions.
 
-4. Add `content` folder
+4. Run `pnpm run generate:docs` script
 
-5. Run `pnpm run generate:docs` script
-
-6. Start the development server:
+5. Start the development server:
 ```bash
 pnpm run dev
 ```
+
+6. After you see that everything works with the current content inside the `content` folder, remove those files and add your own
+
 7. Happy coding!

app/utils/load-content-collections.ts

@@ -1,4 +1,5 @@
-import { resolve } from "node:path"
+import path, { resolve } from "node:path"
+import { pathToFileURL } from "node:url"
 import type { Page } from "content-collections"
 import type { Section } from "content-collections"
 import type { Version } from "./version-resolvers"
@@ -11,11 +12,14 @@ import type { Version } from "./version-resolvers"
  */
 export async function loadContentCollections(version: Version) {
 	const projectRoot = process.cwd()
-
 	const genBase = resolve(projectRoot, "generated-docs", version, ".content-collections", "generated")
 
-	const pagesMod = await import(/* @vite-ignore */ `${genBase}/allPages.js`)
-	const sectionsMod = await import(/* @vite-ignore */ `${genBase}/allSections.js`)
+	const pagesPath = pathToFileURL(path.join(genBase, "allPages.js")).href
+
+	const sectionsPath = pathToFileURL(path.join(genBase, "allSections.js")).href
+
+	const pagesMod = await import(/* @vite-ignore */ pagesPath)
+	const sectionsMod = await import(/* @vite-ignore */ sectionsPath)
 
 	const allPages = pagesMod.default as Page[]
 	const allSections = sectionsMod.default as Section[]

content-collections.ts

@@ -1,3 +1,4 @@
+import { posix } from "node:path"
 import { defineCollection, defineConfig } from "@content-collections/core"
 import { compileMDX } from "@content-collections/mdx"
 import rehypeSlug from "rehype-slug"
@@ -39,12 +40,19 @@ export type Page = z.infer<typeof pageOutputSchema>
 /**
  * Removes leading number prefixes like "01-", "02-" from each path segment.
  */
-const cleanSlug = (path: string) =>
-	path
+const cleanSlug = (p: string) =>
+	toPosix(p)
 		.split("/")
+		.filter(Boolean)
 		.map((seg) => seg.replace(/^\d{2,}-/, ""))
 		.join("/")
 
+const toPosix = (s: string) => {
+	return posix.normalize(s.replace(/\\/g, "/"))
+}
+const stripExt = (s: string) => s.replace(/\.(md|mdx)$/i, "")
+const stripTrailingIndex = (s: string) => s.replace(/\/index$/i, "")
+
 /*
  * This collection defines a documentation section shown in the sidebar of the package documentation.
  *
@@ -57,8 +65,7 @@ const section = defineCollection({
 	include: "**/index.md",
 	schema: sectionSchema,
 	transform: (document) => {
-		const relativePath = document._meta.path.split("/").filter(Boolean).join("/")
-		const slug = cleanSlug(relativePath)
+		const slug = stripTrailingIndex(cleanSlug(document._meta.path))
 		return { ...document, slug }
 	},
 })
@@ -74,14 +81,11 @@ const page = defineCollection({
 	include: "**/**/*.mdx",
 	schema: pageSchema,
 	transform: async (document, context) => {
-		const relativePath = document._meta.path.split("/").filter(Boolean).join("/")
-		const slug = cleanSlug(relativePath)
-		const content = await compileMDX(context, document, {
-			rehypePlugins: [rehypeSlug],
-		})
-
-		// rawMdx is the content without the frontmatter, used to read headings from the mdx file and create a content tree for the table of content component
+		const cleanedSlug = cleanSlug(document._meta.path)
+		const slug = stripExt(cleanedSlug)
+		const content = await compileMDX(context, document, { rehypePlugins: [rehypeSlug] })
 		const rawMdx = document.content.replace(/^---\s*[\r\n](.*?|\r|\n)---/, "").trim()
+
 		return {
 			...document,
 			content,

package.json

@@ -11,7 +11,7 @@
 		"clean": "git clean -fdX --exclude=\"!.env\"",
 		"script": "tsx scripts/setup.ts",
 		"build": "react-router build",
-		"predev": "pnpm run typegen && pnpm run verify:docs",
+		"predev": "run-s typegen verify:docs",
 		"dev": "react-router dev",
 		"start": "NODE_ENV=production node ./build/server/index.js",
 		"pretest": "pnpm run typegen",
@@ -81,6 +81,7 @@
 		"happy-dom": "16.8.1",
 		"knip": "5.43.6",
 		"lefthook": "1.10.10",
+		"npm-run-all": "4.1.5",
 		"playwright": "1.50.1",
 		"prompt": "1.3.0",
 		"react-router-devtools": "5.0.4",