feat(content): custom syntax highlighter and add shiki as one (#1121)

apps/blog-app/src/app/app.config.ts

@@ -1,4 +1,5 @@
 import { provideContent, withMarkdownRenderer } from '@analogjs/content';
+import { withShikiHighlighter } from '@analogjs/content/shiki-highlighter';
 import { provideFileRouter } from '@analogjs/router';
 import { provideHttpClient } from '@angular/common/http';
 import { ApplicationConfig } from '@angular/core';
@@ -13,7 +14,12 @@ export const appConfig: ApplicationConfig = {
     provideHttpClient(),
     provideClientHydration(),
     provideContent(
-      withMarkdownRenderer({ loadMermaid: () => import('mermaid') })
+      withMarkdownRenderer({ loadMermaid: () => import('mermaid') }),
+      withShikiHighlighter({
+        highlighter: {
+          additionalLangs: ['mermaid'],
+        },
+      })
     ),
     provideFileRouter(
       withInMemoryScrolling({ anchorScrolling: 'enabled' }),

apps/blog-app/src/content/2022-12-31-my-second-post.md

@@ -18,6 +18,22 @@ function sum(n1: number, n2: number): number {
 }
 ```
 
+```angular-ts
+@Component({
+  template: `
+    @if (show()) {
+      <div>Hi there</div>
+    } @else {
+      <div>Booo!</div>
+      <button (click)="show.set(false)">Show</button>
+    }
+  `
+})
+export class MyCmp {
+  show = signal(true);
+}
+```
+
 ### Section 2
 
 Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna

apps/blog-app/src/styles.css

@@ -2,4 +2,4 @@
 /* include CSS for prism toolbar */
 @import 'prismjs/plugins/toolbar/prism-toolbar.css';
 /* check node_modules/prismjs/themes/ for the available themes */
-@import 'prismjs/themes/prism-tomorrow';
+@import 'prismjs/themes/prism-tomorrow.css';

apps/docs-app/docs/features/routing/content.md

@@ -1,6 +1,3 @@
-import Tabs from '@theme/Tabs';
-import TabItem from '@theme/TabItem';
-
 # Content Routes
 
 Analog also supports using markdown content as routes, and rendering markdown content in components.
@@ -44,7 +41,25 @@ Analog is a meta-framework for Angular.
 [Back Home](./)
 ```
 
-### Using the diff Highlight Plugin
+### PrismJS Syntax Highlighting
+
+Analog supports syntax highlighting with PrismJS. To enable syntax highlighting with `PrismJS`, add `withPrismHighlighter()` to the `provideContent()` function in `app.config.ts`.
+
+```diff-ts
+import { ApplicationConfig } from '@angular/core';
+import { provideContent, withMarkdownRenderer } from '@analogjs/content';
++ import { withPrismHighlighter } from '@analogjs/content/prism-highlighter';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // ... other providers
+-   provideContent(withMarkdownRenderer()),
++   provideContent(withMarkdownRenderer(), withPrismHighlighter()),
+  ],
+};
+```
+
+#### Using the `diff` Highlight Plugin
 
 Analog supports highlighting diff changes with PrismJS. Add the `diff`
 language and `diff-highlight` plugin imports to `app.config.ts`:
@@ -75,6 +90,110 @@ To highlight changed line backgrounds instead of just the text, add this import
 @import 'prismjs/plugins/diff-highlight/prism-diff-highlight.css';
 ```
 
+### Shiki Syntax Highlighting
+
+Analog also supports syntax highlighting with Shiki. To enable syntax highlighting with `Shiki`, add `withShikiHighlighter()` to the `provideContent()` function in `app.config.ts`.
+
+```diff-ts
+import { ApplicationConfig } from '@angular/core';
+import { provideContent, withMarkdownRenderer } from '@analogjs/content';
++ import { withShikiHighlighter } from '@analogjs/content/shiki-highlighter';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // ... other providers
+-   provideContent(withMarkdownRenderer()),
++   provideContent(withMarkdownRenderer(), withShikiHighlighter()),
+  ],
+};
+```
+
+#### Configure Shiki Highlighter
+
+> Please check out [Shiki Documentation](https://shiki.style/) for more information on configuring Shiki.
+
+To configure Shiki, you can pass a `WithShikiHighlighterOptions` object to the `withShikiHighlighter()` function.
+
+```ts
+import { withShikiHighlighter } from '@analogjs/content/shiki-highlighter';
+
+provideContent(
+  withMarkdownRenderer(),
+  withShikiHighlighter({
+    highlight: { theme: 'nord' },
+  })
+);
+```
+
+By default, `withShikiHighlighter` has the following options.
+
+```json
+{
+  "highlight": {
+    "themes": {
+      "dark": "github-dark",
+      "light": "github-light"
+    }
+  },
+  "highlighter": {
+    "langs": [
+      "json",
+      "ts",
+      "tsx",
+      "js",
+      "jsx",
+      "html",
+      "css",
+      "angular-html",
+      "angular-ts"
+    ],
+    "themes": ["github-dark", "github-light"]
+  }
+}
+```
+
+Provided options will be merged **shallowly**. For example:
+
+```ts
+import { withShikiHighlighter } from '@analogjs/content/shiki-highlighter';
+
+withShikiHighlighter({
+  highlighter: {
+    // langs will be provied by the default options
+    themes: ['ayu-dark'], // only ayu-dark will be bundled
+  },
+  highlight: {
+    theme: 'ayu-dark', // use ayu-dark as the theme
+    // theme: 'dark-plus' // ERROR: dark-plus is not bundled
+  },
+});
+```
+
+### Custom Syntax Highlighter
+
+If you want to use a custom syntax highlighter, you can use the `withHighlighter()` function to provide a custom highlighter.
+
+```ts
+import { withHighlighter, MarkedContentHighlighter } from '@analogjs/content';
+// NOTE: make sure to install 'marked-highlight' if not already installed
+import { markedHighlight } from 'marked-highlight';
+
+class CustomHighlighter extends MarkedContentHighlighter {
+  override getHighlightExtension() {
+    return markedHighlight({
+      highlight: (code, lang) => {
+        return 'your custom highlight';
+      },
+    });
+  }
+}
+
+provideContent(
+  withMarkdownRenderer(),
+  withHighlighter({ useClass: CustomHighlighter })
+);
+```
+
 ## Defining Content Files
 
 For more flexibility, markdown content files can be provided in the `src/content` folder. Here you can list markdown files such as blog posts.

apps/ng-app/src/app/app.config.ts

@@ -1,3 +1,4 @@
+import { withPrismHighlighter } from '@analogjs/content/prism-highlighter';
 import { provideFileRouter } from '@analogjs/router';
 import { provideHttpClient } from '@angular/common/http';
 import { ApplicationConfig } from '@angular/core';
@@ -7,6 +8,10 @@ export const appConfig: ApplicationConfig = {
   providers: [
     provideFileRouter(),
     provideHttpClient(),
-    provideContent(withMarkdownRenderer()),
+    provideContent(
+      withMarkdownRenderer(),
+      // NOTE: .agx files are not affected by the highlighter yet.
+      withPrismHighlighter()
+    ),
   ],
 };

apps/ng-app/src/styles.css

@@ -2,4 +2,4 @@
 /* include CSS for prism toolbar */
 @import 'prismjs/plugins/toolbar/prism-toolbar.css';
 /* check node_modules/prismjs/themes/ for the available themes */
-@import 'prismjs/themes/prism-tomorrow';
+@import 'prismjs/themes/prism-tomorrow.css';

nx.json

@@ -36,6 +36,11 @@
     "@nx/eslint:lint": {
       "inputs": ["default", "{workspaceRoot}/.eslintrc.json"],
       "cache": true
+    },
+    "@nx/js:tsc": {
+      "cache": true,
+      "dependsOn": ["^build"],
+      "inputs": ["production", "^production"]
     }
   },
   "generators": {

package.json

@@ -40,9 +40,6 @@
     "url": "https://github.com/analogjs/analog.git"
   },
   "private": true,
-  "workspaces": [
-    "apps/docs-app"
-  ],
   "dependencies": {
     "@angular/animations": "^18.0.0",
     "@angular/cdk": "^18.0.0",
@@ -83,8 +80,8 @@
     "zone.js": "^0.14.0"
   },
   "devDependencies": {
-    "@angular-devkit/build-angular": "^18.0.0",
     "@angular-devkit/architect": "^0.1800.0",
+    "@angular-devkit/build-angular": "^18.0.0",
     "@angular-devkit/core": "^18.0.0",
     "@angular-devkit/schematics": "^18.0.0",
     "@angular-eslint/eslint-plugin": "17.3.0",
@@ -145,6 +142,8 @@
     "jsonc-eslint-parser": "^2.1.0",
     "kolorist": "^1.6.0",
     "lint-staged": "^13.1.0",
+    "marked-mangle": "^1.1.7",
+    "marked-shiki": "^1.1.0",
     "minimist": "^1.2.7",
     "ng-packagr": "^18.0.0",
     "nitropack": "^2.9.0",
@@ -160,6 +159,7 @@
     "rollup-plugin-visualizer": "^5.9.0",
     "semantic-release": "^22.0.7",
     "semantic-release-replace-plugin": "^1.2.7",
+    "shiki": "^1.6.1",
     "start-server-and-test": "^1.15.4",
     "tailwindcss": "^3.0.2",
     "ts-jest": "29.1.0",

packages/content-plugin/.eslintrc.json

@@ -0,0 +1,32 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": "error"
+      }
+    },
+    {
+      "files": ["./package.json", "./migrations.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/nx-plugin-checks": "error"
+      }
+    }
+  ]
+}

packages/content-plugin/README.md

@@ -0,0 +1,11 @@
+# content-plugin
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build content-plugin` to build the library.
+
+## Running unit tests
+
+Run `nx test content-plugin` to execute the unit tests via [Jest](https://jestjs.io).

packages/content/migrations/migration.json → packages/content-plugin/migrations.json

@@ -1,6 +1,18 @@
 {
-  "$schema": "../../../node_modules/@angular-devkit/schematics/collection-schema.json",
-  "schematics": {},
+  "generators": {
+    "update-markdown-renderer-feature": {
+      "version": "1.5.0-beta.1",
+      "description": "Update withMarkdownRenderer feature with withPrismHighlighter",
+      "implementation": "./src/migrations/update-markdown-renderer-feature/update-markdown-renderer-feature"
+    }
+  },
+  "schematics": {
+    "update-markdown-renderer-feature": {
+      "version": "1.5.0-beta.1",
+      "description": "Update withMarkdownRenderer feature with withPrismHighlighter",
+      "factory": "./src/migrations/update-markdown-renderer-feature/compat"
+    }
+  },
   "packageJsonUpdates": {
     "0.2.0-beta.23": {
       "version": "0.2.0-beta.19",
@@ -38,6 +50,16 @@
           "alwaysAddToPackageJson": true
         }
       }
+    },
+    "1.5.0-beta.1": {
+      "version": "1.4.0",
+      "description": "Adds marked-mangle dependency for deprecated marked feature",
+      "packages": {
+        "marked-mangle": {
+          "version": "^1.1.7",
+          "alwaysAddToPackageJson": true
+        }
+      }
     }
   }
 }

packages/content-plugin/package.json

@@ -0,0 +1,5 @@
+{
+  "name": "content-plugin",
+  "version": "0.0.1",
+  "main": "./src/index.js"
+}