Merge pull request #69 from mrjvs/feat-expose-shiki

Expose Shiki and Remark

apps/create-guider/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neato/create-guider",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Beautiful documentation sites, without all the hassle",
   "main": "./entry.js",
   "type": "module",
@@ -37,7 +37,7 @@
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch --onSuccess 'node dist/index.js'",
-    "lint": "eslint .",
+    "lint": "eslint src",
     "lint:fix": "eslint --fix .",
     "typecheck": "tsc --noEmit"
   },

apps/create-guider/src/index.ts

@@ -1,13 +1,13 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { cancel, intro, outro, spinner, text } from '@clack/prompts';
+import { copy, rename } from 'fs-extra';
 import { assertCancel } from './utils/prompts';
 import { exists } from './utils/files';
-import fs from "fs-extra";
-import path from "path";
-import { fileURLToPath } from 'url';
 
 const distPath = path.dirname(fileURLToPath(import.meta.url));
-const cliRoot = path.join(distPath, "../");
-const mainTemplateDir = path.join(cliRoot, "templates/main");
+const cliRoot = path.join(distPath, '../');
+const mainTemplateDir = path.join(cliRoot, 'templates/main');
 
 const s = spinner();
 intro(`@neato/create-guider`);
@@ -17,19 +17,22 @@ const projectName = await text({
   placeholder: 'my-docs',
   validate(value) {
     if (!/\.?[A-Za-z0-9 _-]+/g.test(value))
-      return "Cannot contain special characters";
+      return 'Cannot contain special characters';
   },
 });
 assertCancel(projectName);
 
-const projectDir = "./" + projectName.toString()
+const projectDir = `./${projectName.toString()}`;
 if (await exists(projectDir)) {
-  cancel("A file or folder with that name already exists");
+  cancel('A file or folder with that name already exists');
 }
 
 s.start('Creating files');
-await fs.copy(mainTemplateDir, projectDir);
-await fs.rename(path.join(projectDir, "_gitignore"), path.join(projectDir, ".gitignore"));
-s.stop('Created files')
+await copy(mainTemplateDir, projectDir);
+await rename(
+  path.join(projectDir, '_gitignore'),
+  path.join(projectDir, '.gitignore'),
+);
+s.stop('Created files');
 
 outro(`Enjoy your new documentation!`);

apps/create-guider/templates/main/package.json

@@ -6,7 +6,7 @@
     "lint": "next lint"
   },
   "dependencies": {
-    "@neato/guider": "^1.0.3",
+    "@neato/guider": "^1.1.0",
     "next": "^14.2.3",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"

apps/docs/package.json

@@ -6,7 +6,8 @@
   "eslintConfig": {
     "extends": [
       "@repo/eslint-config"
-    ]
+    ],
+    "ignorePatterns": ["out/**/*", ".next/**/*"]
   },
   "prettier": "@repo/prettier-config",
   "scripts": {

apps/docs/pages/docs/config/api/errors.mdx

@@ -1,7 +1,7 @@
 # Error handling
 
 Configuration loading has some potentionally confusing error handling.
-By default, it will use the "pretty" assertion mode. This mode **will call process.exit(1)** instead of throwing errors. That means that you aren't able to catch it with a try-catch block.
+By default, it will use the "pretty" assertion mode. **This "pretty" mode will call process.exit(1)** instead of throwing errors. That means that you aren't able to catch it with a try-catch block.
 
 ## The modes
  - `pretty` Log the errors in pretty formatting and colors, then exit the process.

apps/docs/pages/docs/config/api/utils.mdx

@@ -4,7 +4,7 @@ Some helpers that can help you make configuration easier.
 
 ## `zodCoercedBoolean()`
 
-Since `zod` boolean coercion is just doing `Boolean(value)`. You get weird cases like these:
+Since `z.coerce.boolean()` is just doing `Boolean(value) under the hood. You get weird cases like these:
  - `z.coerce.boolean().parse("true"); // => true`;
  - `z.coerce.boolean().parse("false"); // => true`;
  - `z.coerce.boolean().parse("yes"); // => true`;
@@ -14,9 +14,9 @@ Since `zod` boolean coercion is just doing `Boolean(value)`. You get weird cases
 If you use `zodCoercedBoolean()` instead of `z.boolean()`, things will be more as you expect them to be.
 Here is a list of valid values, these are checked while ignoring casing (if its a string):
  - `"true"` -> `true`
- - `"false"` -> `false`
  - `"yes"` -> `true`
- - `"no"` -> `true`
  - `true` -> `true`
- - `false` -> `true`
+ - `"false"` -> `false`
+ - `"no"` -> `false`
+ - `false` -> `false`
  - any other values will be read as `false`

apps/docs/pages/docs/config/guide/basic-example.mdx

@@ -17,7 +17,6 @@ See the code snippet below for a usual setup in projects
       .addFromFile(".env") // loads PORT=8080 from file
       .addFromFile(".json") // loads { "port": 8080 } from file
       .addZodSchema(schema) // validates the loaded data to make sure it follow the schema
-      .freeze() // freezes the object so no changes can be made at runtime
       .load(); // this returns the fully type configuration (type infered from schema)
     ```
   </CodeGroup.Code>

apps/docs/pages/docs/guider/api-reference/setup/guider.mdx

@@ -0,0 +1,56 @@
+# `guider()`
+
+This function is the way you inject Guider into NextJS. You can use its options
+to change how Guider behaves in the compile step.
+
+
+## Example
+
+```tsx title="/next.config.mjs"
+import { guider } from "@neato/guider";
+
+const withGuider = guider({
+  themeConfig: './theme.config.tsx',
+});
+
+export default withGuider({
+  output: 'export',
+});
+```
+
+
+## Reference
+
+```tsx
+function guider(options);
+```
+
+<Field title="options" type="DirectoryOptions" required>
+  Options for the redirect.
+
+  <Field.Properties defaultOpen>
+    <Field title="themeConfig" type="string" required>
+      The location of the theme file, the theme file is used to configure almost everything about guider.
+    </Field>
+    <Field title="extraRemarkPlugins" type="RemarkPlugin[]">
+      A list where you can specify [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) to use on top of the default list of plugins.
+
+      Use it to add new features to your markdown files.
+    </Field>
+    <Field title="remarkPlugins" type="RemarkPlugin[]">
+      A list where you can specify [remark plugins](https://github.com/remarkjs/remark/blob/main/doc/plugins.md) to use **instead of the default Guider plugins**.
+
+      Use it to overwrite how markdown parsing works. **Be aware that this will disable a lot of the default features of Guider, use at your own risk.** Use `extraRemarkPlugins` instead if you want to add extra plugins without breaking existing functionality.
+    </Field>
+    <Field title="extraShikiTransformers" type="ShikiTransformer[]">
+      A list where you can specify [Shiki transformers](https://shiki.style/guide/transformers) to use on top of the default transformers.
+
+      Use it to add new features to syntax highlighting in codeblocks.
+    </Field>
+    <Field title="shikiTransformers" type="ShikiTransformer[]">
+      A list where you can specify [Shiki transformers](https://shiki.style/guide/transformers) to use **instead of the default Guider transformers**.
+
+      Use it to overwrite how syntax highlighting works in Guider. **Be aware that this will disable a lot of the default features of Guider, use at your own risk.** Use `extraShikiTransformers` instead if you want to add extra transformers without breaking existing functionality.
+    </Field>
+  </Field.Properties>
+</Field>

apps/docs/pages/showcase.tsx

@@ -4,8 +4,6 @@ import { Showcase } from 'components/showcase-layout';
 import type { ShowcaseTag, ShowcaseType } from 'components/showcase-card';
 import { ShowcaseCard, ShowcaseCardContainer } from 'components/showcase-card';
 import pretendoImg from 'public/showcases/pretendo.png';
-import mwAccountImg from 'public/showcases/movie-web-account.png';
-import mwDocsImg from 'public/showcases/movie-web-docs.png';
 
 const showcases: ShowcaseType[] = [
   {
@@ -15,20 +13,6 @@ const showcases: ShowcaseType[] = [
     imageUrl: pretendoImg.src,
     tags: ['guider'],
   },
-  {
-    title: 'movie-web backend',
-    description: 'Uses Config for their account service.',
-    href: 'https://github.com/movie-web/backend/',
-    imageUrl: mwAccountImg.src,
-    tags: ['config'],
-  },
-  {
-    title: 'movie-web docs',
-    description: 'Uses Guider for their documentation',
-    href: 'https://github.com/movie-web/docs/',
-    imageUrl: mwDocsImg.src,
-    tags: ['guider'],
-  },
 ];
 
 export default function ShowcasePage() {

apps/docs/postcss.config.js

@@ -3,4 +3,4 @@ module.exports = {
     tailwindcss: {},
     autoprefixer: {},
   },
-}
+};

apps/docs/theme.config.tsx

@@ -216,6 +216,8 @@ export default defineTheme([
             link('Layout settings', gdApi('/theme/settings')),
           ]),
 
+          group('Setup', [link('guider()', gdApi('/setup/guider'))]),
+
           group('_meta.json', [
             link('Structure of _meta.json', gdApi('/meta/structure')),
           ]),

packages/guider/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neato/guider",
-  "version": "1.0.3",
+  "version": "1.1.0",
   "description": "Beautiful documentation sites, without all the hassle",
   "main": "./dist/index.js",
   "type": "module",
@@ -51,7 +51,12 @@
   "eslintConfig": {
     "extends": [
       "@repo/eslint-config"
-    ]
+    ],
+    "ignorePatterns": ["dist/**/*", "style.css"],
+    "rules": {
+      "import/no-named-as-default": "off",
+      "import/no-named-as-default-member": "off"
+    }
   },
   "prettier": "@repo/prettier-config",
   "scripts": {

packages/guider/src/index.ts

@@ -11,7 +11,7 @@ export function guider(initConfig: GuiderInitConfig) {
     ...initConfig,
   };
   const guiderPlugin = new GuiderPlugin(guiderConfig);
-  const searchPlugin = new GuiderSearchPlugin();
+  const searchPlugin = new GuiderSearchPlugin(guiderConfig);
 
   function withGuider(nextConfig: NextConfig = {}): NextConfig {
     const extraWatchers = new ExtraWatchWebpackPlugin({

packages/guider/src/types.ts

@@ -1,3 +1,30 @@
+import type { ShikiTransformer } from 'shiki';
+import type { PluggableList } from 'unified';
+
 export type GuiderInitConfig = {
+  /**
+   * The location of the theme config
+   */
   themeConfig: string;
+
+  /**
+   * Extra shiki transformers added to syntax highlighted code
+   */
+  extraShikiTransformers?: ShikiTransformer[];
+
+  /**
+   * Replaces all shiki transformers added to syntax highlighted code
+   */
+  shikiTransformers?: ShikiTransformer[];
+
+  /**
+   * Extra remark plugins added to markdown parsing
+   */
+  extraRemarkPlugins?: PluggableList;
+
+  /**
+   * Replaces all remark plugins added to markdown parsing
+   * NOTE: This disables and breaks a lot of features of Guider, use at your own risk.
+   */
+  remarkPlugins?: PluggableList;
 };

packages/guider/src/webpack/loader/index.ts

@@ -23,7 +23,11 @@ async function loader(
   if (directories.pagesDir) context.addContextDependency(directories.pagesDir);
 
   if (type === 'virtual') return virtualLoader(getGuiderPluginCache());
-  if (type === 'mdx') return (await mdLoader(source)).script;
+  if (type === 'mdx') {
+    if (!guiderConfig)
+      throw new Error('Could not read config for markdown loader');
+    return (await mdLoader(source, guiderConfig)).script;
+  }
 
   throw new Error(`Loader used with incorrect type (${type})`);
 }