doc: switch to docusaurus

Desdaemon · Aug 4, 2023 · 0e0fed5 · 0e0fed5
1 parent b7e50d4
commit 0e0fed5
Show file tree

Hide file tree

Showing 33 changed files with 9,694 additions and 573 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -10,31 +10,37 @@ concurrency:
   group: docs-${{ github.ref }}
   cancel-in-progress: true
 
+defaults:
+  run:
+    working-directory: docs
+
 jobs:
   build:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3
-      - uses: abatilo/actions-poetry@v2
-      - uses: actions/cache@v3
-        with:
-          path: .venv
-          key: venv-${{ hashFiles('poetry.lock') }}
-      - run: poetry install
       - uses: pnpm/action-setup@v2
         with:
           version: 8
       - uses: actions/setup-node@v3
         with:
           cache: pnpm
-          cache-dependency-path: pnpm-lock.yaml
+          cache-dependency-path: docs/pnpm-lock.yaml
+
+      - run: pnpm install
+        working-directory: .
+      - name: Build library
+        run: pnpm dist
+        working-directory: .
+
       - run: pnpm install
+      - run: pnpm docusaurus generate-typedoc
       - name: Build website
-        run: pnpm doc build -d website
+        run: pnpm build
       - name: Upload artifacts
         uses: actions/upload-pages-artifact@v1
         with:
-          path: website
+          path: docs/build
   deploy:
     needs: build
     permissions:

diff --git a/README.md b/README.md
@@ -16,7 +16,7 @@ templating engine.
 
 Configure your `tsconfig.json` as follows:
 
-```json
+```jsonc
 {
   "compilerOptions": {
     "jsx": "react",
@@ -51,7 +51,7 @@ library and optimized for htmx usage:
 
 Configure your `tsconfig.json` as follows:
 
-```json
+```jsonc
 {
   "compilerOptions": {
     "jsx": "react-jsx",

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,21 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+docs/api
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
diff --git a/docs/README.md b/docs/README.md
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,41 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ yarn
+```
+
+### Local Development
+
+```
+$ yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+### Deployment
+
+Using SSH:
+
+```
+$ USE_SSH=true yarn deploy
+```
+
+Not using SSH:
+
+```
+$ GIT_USER=<Your GitHub username> yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.
diff --git a/docs/babel.config.js b/docs/babel.config.js
@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};
diff --git a/docs/docs/.nojekyll b/docs/docs/.nojekyll
diff --git a/docs/docs/howto/intro.md b/docs/docs/howto/intro.md
@@ -0,0 +1,72 @@
+# Intro
+
+## Demo
+
+```tsx twoslash
+// @errors: 2322
+
+function MyComponent({ children }) {
+  return '<!DOCTYPE html>' + (
+    <html lang='en'>
+      <head>
+        <title>My Website</title>
+      </head>
+      <body hx-boost hx-ext='sse'>
+        <div id='main'>
+          {children}
+          <form hx-post='/purchase' hx-swap='outerHTML' hx-vals={{foo: 'bar'}}>
+            <button type='submit'>Buy Now</button>
+          </form>
+        </div>
+      </body>
+    </html>
+  )
+}
+```
+
+## Tips
+
+### Configuring the JSX runtime
+
+If you don't have any other JSX runtimes like React or Preact set up, you can use
+the one bundled with typed-htmx which will compile JSX into strings at runtime.
+You can also configure the runtime like this:
+
+```js twoslash
+import { jsxConfig } from 'typed-htmx'
+// Set to true to allow all text and skip sanitization
+jsxConfig.trusted = true
+// Bring your own sanitizer
+jsxConfig.sanitize = (raw, originalType) => `..`
+```
+
+### Compiling JSX templates
+
+JSX functions are fairly fast and will unlikely to be a bottleneck in your server.
+However, it is possible to achieve higher performance via techniques such as code transformations à la Babel.
+For example, you can use [`swc-plugin-static-jsx`](https://github.com/Desdaemon/swc-plugin-static-jsx)
+which will transform the demo snippet into pure string interpolation:
+
+```ts
+// User-provided template function
+function html(raw: TemplateStringsArray, ...args: unknown[]): string {
+  // ..
+}
+
+function MyComponent({ children }) {
+  return '<!DOCTYPE html>' + html`
+    <html lang="en">
+      <head>
+        <title>My Website</title>
+      </head>
+      <body hx-boost hx-ext="sse">
+        <div id="main">
+          ${{$$child: children}}
+          <form hx-post="/purchase" hx-swap="outerHTML" ${{'hx-vals': {foo: 'bar'}}}>
+            <button type="submit">Buy Now</button>
+          </form>
+        </div>
+      </body>
+    </html>`
+}
+```
diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js
@@ -0,0 +1,183 @@
+// @ts-check
+// Note: type annotations allow type checking and IDEs autocompletion
+
+const lightCodeTheme = require('prism-react-renderer/themes/github');
+const darkCodeTheme = require('prism-react-renderer/themes/dracula');
+
+/** @type {import('@docusaurus/types').Config} */
+const config = {
+  title: 'typed-htmx',
+  tagline: 'JSX definitions for htmx',
+  favicon: 'img/favicon.ico',
+
+  url: 'https://desdaemon.github.io',
+  // Set the /<baseUrl>/ pathname under which your site is served
+  // For GitHub pages deployment, it is often '/<projectName>/'
+  baseUrl: '/typed-htmx/',
+
+  // GitHub pages deployment config.
+  // If you aren't using GitHub pages, you don't need these.
+  organizationName: 'Desdaemon', // Usually your GitHub org/user name.
+  projectName: 'typed-htmx', // Usually your repo name.
+
+  onBrokenLinks: 'throw',
+  onBrokenMarkdownLinks: 'ignore',
+
+  // Even if you don't use internalization, you can use this field to set useful
+  // metadata like html lang. For example, if your site is Chinese, you may want
+  // to replace "en" with "zh-Hans".
+  i18n: {
+    defaultLocale: 'en',
+    locales: ['en'],
+  },
+
+  plugins: [
+    ['docusaurus-plugin-typedoc', /** @type {Partial<import('docusaurus-plugin-typedoc').PluginOptions>} */
+      ({
+        entryPoints: [
+          '../src/index.ts',
+          '../src/jsx.d.ts',
+        ],
+        tsconfig: '../tsconfig.json',
+        readme: 'none',
+        hideInPageTOC: true,
+        watch: process.env.npm_lifecycle_event === 'start',
+        // cleanOutputDir: process.env.NODE_ENV !== 'production',
+        cleanOutputDir: false,
+        excludeExternals: true,
+        externalPattern: [
+          'node_modules/**/*',
+        ]
+    })],
+  ],
+
+  presets: [
+    [
+      'classic',
+      /** @type {import('@docusaurus/preset-classic').Options} */
+      ({
+        docs: {
+          sidebarPath: require.resolve('./sidebars.js'),
+          // Please change this to your repo.
+          // Remove this to remove the "edit this page" links.
+          // editUrl:
+          //   'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+        },
+        // blog: {
+        //   showReadingTime: true,
+        //   // Please change this to your repo.
+        //   // Remove this to remove the "edit this page" links.
+        //   editUrl:
+        //     'https://github.com/facebook/docusaurus/tree/main/packages/create-docusaurus/templates/shared/',
+        // },
+        theme: {
+          customCss: require.resolve('./src/css/custom.css'),
+        },
+      }),
+    ],
+    ['docusaurus-preset-shiki-twoslash', {
+      themes: ['min-light', 'nord'],
+      tsModule: require('typescript'),
+      defaultOptions: {
+        noErrors: false,
+      },
+      defaultCompilerOptions: {
+        types: ['typed-htmx'],
+        jsx: 'react-jsx',
+        jsxImportSource: 'typed-htmx/typed-html',
+        target: 'esnext',
+        strict: true,
+        noImplicitAny: false,
+        moduleResolution: 99 // nodenext
+      },
+      includeJSDocInHover: true,
+    }]
+  ],
+
+  themeConfig:
+    /** @type {import('@docusaurus/preset-classic').ThemeConfig} */
+    ({
+      // Replace with your project's social card
+      image: 'img/docusaurus-social-card.jpg',
+      navbar: {
+        title: 'typed-htmx',
+        logo: {
+          alt: 'My Site Logo',
+          src: 'img/logo.svg',
+        },
+        items: [
+          {
+            type: 'docSidebar',
+            sidebarId: 'docsSidebar',
+            position: 'left',
+            label: 'Usage',
+          },
+          {
+            type: 'docSidebar',
+            sidebarId: 'referenceSidebar',
+            position: 'left',
+            label: 'Reference',
+          },
+          {
+            href: 'https://github.com/Desdaemon/typed-htmx',
+            label: 'GitHub',
+            position: 'right',
+          },
+        ],
+      },
+      footer: {
+        style: 'dark',
+        links: [
+          {
+            title: 'Docs',
+            items: [
+              {
+                label: 'Usage',
+                to: '/docs/howto/intro',
+              },
+              {
+                label: 'Reference',
+                to: '/docs/api'
+              }
+            ],
+          },
+          // {
+          //   title: 'Community',
+          //   items: [
+          //     {
+          //       label: 'Stack Overflow',
+          //       href: 'https://stackoverflow.com/questions/tagged/docusaurus',
+          //     },
+          //     {
+          //       label: 'Discord',
+          //       href: 'https://discordapp.com/invite/docusaurus',
+          //     },
+          //     {
+          //       label: 'Twitter',
+          //       href: 'https://twitter.com/docusaurus',
+          //     },
+          //   ],
+          // },
+          // {
+          //   title: 'More',
+          //   items: [
+          //     {
+          //       label: 'Blog',
+          //       to: '/blog',
+          //     },
+          //     {
+          //       label: 'GitHub',
+          //       href: 'https://github.com/facebook/docusaurus',
+          //     },
+          //   ],
+          // },
+        ],
+      },
+      prism: {
+        theme: lightCodeTheme,
+        darkTheme: darkCodeTheme,
+      },
+    }),
+};
+
+module.exports = config;