[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-action`
+      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,19 @@
+// @ts-check
+
+const options = {
+  config: {
+    default: true,
+    "relative-links": true,
+    MD041: false,
+    MD013: false,
+    "no-inline-html": {
+      // Add React components we want to allow here
+      allowed_elements: ["LoginOrUserInfo", "Info"],
+    },
+  },
+  globs: ["src/pages/**/*.{md,mdx}"],
+  ignores: ["**/node_modules", "theme", "scripts"],
+  customRules: ["markdownlint-rule-relative-links"],
+};
+
+export default options;

contentlayer.config.js

@@ -0,0 +1,26 @@
+import { defineDocumentType, makeSource } from 'contentlayer2/source-files'
+
+const computedFieldsPage = {
+  slug: {
+    type: 'string',
+    resolve: (doc) => doc._raw.sourceFileName.replace(/\.mdx$/, ''),
+  },
+}
+
+export const Page = defineDocumentType(() => ({
+  name: 'Page',
+  filePathPattern: `**/*.mdx`,
+  computedFieldsPage,
+}))
+
+export const MetaJson = defineDocumentType(() => ({
+  name: 'MetaJson',
+  filePathPattern: `**/_meta.json`,
+}))
+
+export default makeSource({
+  contentDirPath: 'src/pages',
+  documentTypes: [Page],
+  onUnknownDocuments: 'skip-ignore'
+
+})

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",