Deploy Typedoc docs to GitHub pages

Author: martijnversluis

.github/workflows/ci.yml

@@ -47,12 +47,12 @@ jobs:
         run: yarn install
       - name: Run tests
         run: yarn ci
-  verify-readme:
+  generate-typedoc:
     runs-on: ubuntu-latest
     strategy:
       matrix:
         node-version: [ 22.6 ]
-    name: Verify README.md
+    name: Generate typedoc
     steps:
       - uses: actions/checkout@v4
       - name: Use Node.js ${{ matrix.node-version }}
@@ -63,8 +63,16 @@ jobs:
         run: corepack enable
       - name: Install node modules
         run: yarn install
-      - name: Verify README.md
-        run: yarn readme && git diff README.md
+      - name: Build
+        run: yarn build
+      - name: Generate typedoc
+        run: yarn typedoc
+      - name: Store artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: github-pages
+          path: tmp/docs
+          if-no-files-found: error
   verify-install:
     runs-on: ubuntu-latest
     strategy:
@@ -80,3 +88,19 @@ jobs:
         run: corepack enable
       - name: Verify install
         run: YARN_ENABLE_IMMUTABLE_INSTALLS=false npm install "https://github.com/martijnversluis/ChordSheetJS/tree/$GITHUB_SHA"
+
+  typedoc:
+    runs-on: ubuntu-latest
+    needs: generate-typedoc
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          artifact_name: github-pages

.github/workflows/release.yml

@@ -21,3 +21,23 @@ jobs:
         uses: softprops/action-gh-release@v2
         with:
           files: lib/bundle.js
+      - name: Store artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: github-pages
+          path: tmp/docs
+
+  typedoc:
+    runs-on: ubuntu-latest
+    needs: build
+    permissions:
+      pages: write      # to deploy to Pages
+      id-token: write   # to verify the deployment originates from an appropriate source
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}

package.json

@@ -58,7 +58,6 @@
     "tsc": "^2.0.4",
     "tsx": "^4.10.5",
     "typedoc": "^0.27.1",
-    "typedoc-plugin-markdown": "^4.3.0",
     "typescript": "^5.6.2",
     "typescript-eslint": "^8.6.0"
   },

src/chord_sheet/metadata.ts

@@ -88,8 +88,7 @@ class Metadata extends MetadataAccessors {
    *
    * This method deprecates direct property access, eg: metadata['author']
    *
-   * Examples:
-   *
+   * @example
    * const metadata = new Metadata({ lyricist: 'Pete', author: ['John', 'Mary'] });
    * metadata.get('lyricist') // => 'Pete'
    * metadata.get('author')   // => ['John', 'Mary']

typedoc.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["./src/index.ts"],
+  "out": "tmp/docs",
+  "excludeNotDocumented": true,
+  "logLevel": "Error"
+}

unibuild.ts

@@ -11,7 +11,7 @@ import buildScales from './script/build_scales';
 import buildChordProSectionGrammar from './script/build_chord_pro_section_grammar';
 
 const {
-  main, source, types, bundle,
+  main, types, bundle,
 } = packageJSON;
 
 interface BuildOptions {
@@ -113,21 +113,6 @@ unibuild((u: Builder) => {
     chordDefinitionParser,
   ];
 
-  u.asset('readme', {
-    input: ['INTRO.md', 'src', ...codeGeneratedAssets],
-    outfile: 'README.md',
-    command: ({ input: [intro], outfile }) => {
-      const tmpDir = 'tmp/docs';
-      return [
-        `typedoc --plugin typedoc-plugin-markdown  --out ${tmpDir} ${source} --logLevel Error`,
-        `cat ${intro} > ${outfile}`,
-        `concat-md --decrease-title-levels --dir-name-as-title ${tmpDir} >> ${outfile}`,
-        `rm -rf ${tmpDir}`,
-      ];
-    },
-    releaseOnly: true,
-  });
-
   const jsBuild = u.asset('sources', {
     input: codeGeneratedAssets,
     outfile: main,

yarn.lock

@@ -3555,7 +3555,6 @@ __metadata:
     tsc: "npm:^2.0.4"
     tsx: "npm:^4.10.5"
     typedoc: "npm:^0.27.1"
-    typedoc-plugin-markdown: "npm:^4.3.0"
     typescript: "npm:^5.6.2"
     typescript-eslint: "npm:^8.6.0"
   languageName: unknown
@@ -9386,15 +9385,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"typedoc-plugin-markdown@npm:^4.3.0":
-  version: 4.3.0
-  resolution: "typedoc-plugin-markdown@npm:4.3.0"
-  peerDependencies:
-    typedoc: 0.27.x
-  checksum: 10c0/2db27e6508fc0047b9608edc084b6c43bbe88e03dbdc288b33a77ecba75d1c5561236b5e5df2153b50ff781d79684a90d6b2b1c099f20839310275cb4e142eb7
-  languageName: node
-  linkType: hard
-
 "typedoc@npm:^0.27.1":
   version: 0.27.1
   resolution: "typedoc@npm:0.27.1"