[PR] Linting markdown files and checking for broken internal and external links

.github/workflows/ci.yml

@@ -23,6 +23,14 @@ jobs:
     - name: Install dependencies
       run: pnpm install --no-frozen-lockfile
 
+    # Run `markdownlint-cli2` to lint markdown files
+    - name: Running `markdownlint-cli2`
+      run: pnpm run lint:check-markdown
+
+    # Run script to check for dead links
+    - name: Checking for dead links
+      run: pnpm run lint:check-external-links
+
     # Run build
     - name: Build Next.js app
       run: pnpm run build

.gitignore

@@ -139,4 +139,7 @@ dist
 /playwright-report/
 /blob-report/
 /playwright/.cache/
-/.swc
+/.swc
+
+# Content layer
+.contentlayer

.markdownlint-cli2.mjs

@@ -0,0 +1,26 @@
+// @ts-check
+const options = {
+
+  // Overriding default configs
+  config: {
+    default: true,
+    MD041: false,             // https://github.com/DavidAnson/markdownlint/blob/main/doc/md041.md
+    MD013: false,             // https://github.com/DavidAnson/markdownlint/blob/main/doc/md013.md
+    "no-inline-html": {
+      // Add React components we want to allow here
+      allowed_elements: ["LoginOrUserInfo", "Info"],
+    },
+    "relative-links": true,   // Setting the custom `markdownlint-reule-relative-links` rule
+  },
+
+  // Run the lint in the following directory
+  globs: ["src/pages/**/*.{md,mdx}"],
+
+  // Don't run lint in these directories
+  ignores: ["**/node_modules", "theme", "scripts"],
+
+  // Import custom rules
+  customRules: ["markdownlint-rule-relative-links"],
+};
+
+export default options;

README.md

@@ -26,14 +26,16 @@ https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one
 - [What? ✨](#what-)
 - [Who? 👥](#who-)
 - [How? 👩‍💻](#how-)
+  - [Run the _Finished_ Project](#run-the-finished-project)
     - [1. Clone the Project](#1-clone-the-project)
     - [2. Install Dependencies](#2-install-dependencies)
     - [3. Create Environment Variables](#3-create-environment-variables)
     - [4. Run the App!](#4-run-the-app)
   - [Run the Tests!](#run-the-tests)
   - [Build It!](#build-it)
-  - [_Please_ star the repo! ⭐️](#please-star-the-repo-️)
-  - [Troubleshooting](#troubleshooting)
+- [_Please_ star the repo! ⭐️](#please-star-the-repo-️)
+- [Troubleshooting](#troubleshooting)
+  - [I'm getting an error pertaining a missing secret](#im-getting-an-error-pertaining-a-missing-secret)
 
 
 # Why? 🤷‍♀️
@@ -107,7 +109,7 @@ or just want to discuss this further,
 
 Ready? Let's go! 🚀
 
-## Run the _Finished_ Project
+## Run the _Finished_ Project
 
 ### 1. Clone the Project
 
@@ -193,17 +195,17 @@ See:
 [tutorial.md](./tutorial.md)
 
 
-## _Please_ star the repo! ⭐️
+# _Please_ star the repo! ⭐️
 
 If you find this repo/tutorial useful,
 please star it on GitHub, so that we know! ⭐
 
 Thank you! 🙏
 
 
-## Troubleshooting
+# Troubleshooting
 
-### I'm getting an error pertaining a missing secret
+## I'm getting an error pertaining a missing secret
 
 You may have encountered the following error.
 

contentlayer.config.js

@@ -0,0 +1,29 @@
+import { defineDocumentType, makeSource } from 'contentlayer2/source-files'
+
+// This function computes the fields to add to the `Page` document type
+const computedFieldsPage = {
+  slug: {
+    type: 'string',
+    resolve: (doc) => doc._raw.sourceFileName.replace(/\.mdx$/, ''),
+  },
+}
+
+// Define the document type for a `Page` (an `.mdx` file).
+export const Page = defineDocumentType(() => ({
+  name: 'Page',
+  filePathPattern: `**/*.mdx`,
+  computedFieldsPage,
+}))
+
+// Define the document type for each `_meta.json` file
+export const MetaJson = defineDocumentType(() => ({
+  name: 'MetaJson',
+  filePathPattern: `**/_meta.json`,
+}))
+
+export default makeSource({
+  contentDirPath: 'src/pages',
+  documentTypes: [Page],
+  onUnknownDocuments: 'skip-ignore'
+
+})

jest.config.ts

@@ -12,15 +12,15 @@ const createJestConfig = nextJest({
 });
 
 const config: Config = {
+  setupFiles: ["./jest.polyfills.js"],
+
   collectCoverage: true,
-  collectCoverageFrom: ["src/**/*.{js,jsx,ts,tsx}", "!<rootDir>/node_modules/"],
+  collectCoverageFrom: ["src/**/*.{js,jsx,ts,tsx}", "scripts/*.{mjs,js,jsx,ts,tsx}", "!<rootDir>/node_modules/"],
   coverageDirectory: "coverage",
   coveragePathIgnorePatterns: ["/node_modules/"],
   coverageProvider: "v8",
 
-  moduleDirectories: [
-    "node_modules"
-  ],
+  moduleDirectories: ["node_modules"],
   modulePathIgnorePatterns: [
     // Testing auth with `next-auth` complains (consider switching to Vitest)
     // Doesn't seem to have a proper solution. See https://github.com/nextauthjs/next-auth/issues/4198.
@@ -36,10 +36,11 @@ const config: Config = {
     "src/pages/_app.ts",
 
     // The `app` folder is only used to export the default handlers from `next-auth`.
-    "src/app"
+    "src/app",
   ],
   moduleNameMapper: {
     "next-auth/(.*)": "<rootDir>/node_modules/next-auth/$1",
+    "^uuid$": require.resolve("uuid"), // See https://github.com/uuidjs/uuid/issues/451#issuecomment-1377066303.
   },
 
   testEnvironment: "jsdom",

jest.polyfills.js

@@ -0,0 +1,31 @@
+// jest.polyfills.js
+/**
+ * From https://mswjs.io/docs/migrations/1.x-to-2.x#requestresponsetextencoder-is-not-defined-jest.
+ * @note The block below contains polyfills for Node.js globals
+ * required for Jest to function when running JSDOM tests.
+ * These HAVE to be require's and HAVE to be in this exact
+ * order, since "undici" depends on the "TextEncoder" global API.
+ *
+ * Consider migrating to a more modern test runner if
+ * you don't want to deal with this.
+ */
+
+const { TextDecoder, TextEncoder } = require('node:util')
+
+Object.defineProperties(globalThis, {
+  TextDecoder: { value: TextDecoder },
+  TextEncoder: { value: TextEncoder },
+})
+
+const { Blob, File } = require('node:buffer')
+const { fetch, Headers, FormData, Request, Response } = require('undici')
+
+Object.defineProperties(globalThis, {
+  fetch: { value: fetch, writable: true },
+  Blob: { value: Blob },
+  File: { value: File },
+  Headers: { value: Headers },
+  FormData: { value: FormData },
+  Request: { value: Request },
+  Response: { value: Response },
+})

next.config.js

@@ -1,7 +1,10 @@
+
+const withPlugins = require('next-compose-plugins');
 const withNextra = require("nextra")({
   theme: "./theme/src/index.tsx",
   themeConfig: "./theme.config.tsx",
   defaultShowCopyCode: true
 });
+const { withContentlayer } = require('next-contentlayer2');
 
-module.exports = withNextra();
+module.exports = withPlugins([withNextra, withContentlayer]);

package.json

@@ -9,28 +9,38 @@
     "e2e:test": "npx playwright test",
     "e2e:test:show-report": "npx monocart show-report ./e2e-test-results/monocart-report.html",
     "test": "jest --runInBand",
-    "types:check": "tsc --noEmit"
+    "types:check": "tsc --noEmit",
+    "lint:fix-markdown": "markdownlint-cli2 --fix",
+    "lint:check-markdown": "markdownlint-cli2",
+    "lint:check-external-links": "contentlayer2 build --verbose && node scripts/link-check.mjs"
   },
   "dependencies": {
     "next": "^14.2.4",
     "next-auth": "5.0.0-beta.19",
+    "next-compose-plugins": "^2.2.1",
     "nextra": "^2.13.4",
     "nextra-theme-docs": "^2.13.4",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },
   "devDependencies": {
+    "@actions/core": "^1.10.1",
     "@playwright/test": "^1.44.1",
     "@testing-library/jest-dom": "^6.4.6",
     "@testing-library/react": "^16.0.0",
     "@types/jest": "^29.5.12",
     "@types/node": "20.14.5",
     "autoprefixer": "^10.4.19",
+    "contentlayer2": "^0.5.0",
     "dotenv": "^16.4.5",
     "fast-glob": "^3.3.2",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "markdown-link-check": "^3.12.2",
+    "markdownlint-cli2": "^0.13.0",
+    "markdownlint-rule-relative-links": "^3.0.0",
     "monocart-reporter": "^2.5.0",
+    "next-contentlayer2": "^0.5.0",
     "open-cli": "^8.0.0",
     "postcss": "^8.4.31",
     "tailwindcss": "^3.3.3",