From a07dde339c82c480add851568cc3ed018b143e2f Mon Sep 17 00:00:00 2001 From: Milana Cap Date: Wed, 24 Jun 2026 16:29:42 +0200 Subject: [PATCH 1/6] Test including docs from other repositories, while keeping those docs in their current repositories. Signed-off-by: Milana Cap --- .github/workflows/test-deploy.yml | 11 ++++++-- docs/docusaurus.config.js | 33 ++++-------------------- docs/navbarItems.js | 42 +++++++++++++++++++++++++++++++ docs/plugins.js | 19 ++++++++++++++ docs/sidebars-tsc.js | 34 +++++++++++++++++++++++++ 5 files changed, 109 insertions(+), 30 deletions(-) create mode 100644 docs/navbarItems.js create mode 100644 docs/plugins.js create mode 100644 docs/sidebars-tsc.js diff --git a/.github/workflows/test-deploy.yml b/.github/workflows/test-deploy.yml index 4d7a4c2..56862b9 100644 --- a/.github/workflows/test-deploy.yml +++ b/.github/workflows/test-deploy.yml @@ -9,7 +9,7 @@ on: # Allow running this workflow manually from the Actions tab workflow_dispatch: - + defaults: run: shell: bash @@ -23,10 +23,17 @@ jobs: name: Test deployment runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - name: Checkout Docusaurus site + uses: actions/checkout@v4 with: fetch-depth: 0 + - name: Checkout TSC faqs + uses: actions/checkout@v4 + with: + repository: fairpm/tsc + path: external/tsc/faq + - uses: actions/setup-node@v4 with: node-version: 20 diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index 600cb74..c887aeb 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -5,6 +5,8 @@ // See: https://docusaurus.io/docs/api/docusaurus-config import {themes as prismThemes} from 'prism-react-renderer'; +import navbarItems from './navbarItems.js'; +import plugins from './plugins.js'; // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) @@ -80,34 +82,7 @@ const config = { // alt: 'FAIR Logo', // src: 'img/logo.svg', // }, - items: [ - { - type: 'docSidebar', - sidebarId: 'tutorialSidebar', - position: 'left', - label: 'Docs', - }, - { - to: '/blog', - label: 'Blog', - position: 'left' - }, - { - to: 'docs/contributing', - label: 'Get involved', - position: 'left' - }, - { - href: 'https://github.com/fairpm/docs', - label: 'GitHub', - position: 'right', - }, - { - href: 'https://fair.pm/', - label: 'fair.pm', - position: 'right', - }, - ], + items: navbarItems, }, footer: { style: 'dark', @@ -167,6 +142,8 @@ const config = { darkTheme: prismThemes.dracula, }, }), + + plugins: plugins, }; export default config; diff --git a/docs/navbarItems.js b/docs/navbarItems.js new file mode 100644 index 0000000..71a1fb2 --- /dev/null +++ b/docs/navbarItems.js @@ -0,0 +1,42 @@ +// @ts-check + + +const navbarItems = [ + { + type: 'docSidebar', + sidebarId: 'tutorialSidebar', + position: 'left', + label: 'Docs', + }, + { + to: '/blog', + label: 'Blog', + position: 'left' + }, + { + to: 'docs/contributing', + label: 'Get involved', + position: 'left' + }, + { + href: 'https://github.com/fairpm/docs', + label: 'GitHub', + position: 'right', + }, + { + href: 'https://fair.pm/', + label: 'fair.pm', + position: 'right', + }, +]; + +navbarItems.push({ + type: 'docSidebar', + sidebarId: 'tscSidebar', + docsPluginId: 'tsc', + position: 'left', + label: 'TSC', +}); + + +export default navbarItems; diff --git a/docs/plugins.js b/docs/plugins.js new file mode 100644 index 0000000..cd5e13c --- /dev/null +++ b/docs/plugins.js @@ -0,0 +1,19 @@ +// @ts-check + + +const plugins = [ + [ + '@docusaurus/plugin-content-docs', + { + id: 'tsc', + path: 'external/tsc/faq', + routeBasePath: 'tsc', + sidebarPath: require.resolve('./sidebars-tsc.js'), + editUrl: ({docPath}) => + `https://github.com/fairpm/tsc/blob/main/faqs/${docPath}`, + }, + ], +]; + + +export default plugins; diff --git a/docs/sidebars-tsc.js b/docs/sidebars-tsc.js new file mode 100644 index 0000000..e3be94c --- /dev/null +++ b/docs/sidebars-tsc.js @@ -0,0 +1,34 @@ +// @ts-check + +// This runs in Node.js - Don't use client-side code here (browser APIs, JSX...) + +/** + * Creating a sidebar enables you to: + - create an ordered group of docs + - render a sidebar for each doc of that group + - provide next/previous navigation + + The sidebars can be generated from the filesystem, or explicitly defined here. + + Create as many sidebars as you want. + + @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} + */ +const sidebarsTsc = { + // By default, Docusaurus generates a sidebar from the docs folder structure + tscSidebar: [{type: 'autogenerated', dirName: '.'}], + + // But you can create a sidebar manually + +// tscSidebar: [ +// 'intro', +// 'hello', +// { +// type: 'category', +// label: 'Tutorial', +// items: ['tutorial-basics/create-a-document'], +// }, +// ], +}; + +export default sidebarsTsc; From e925b78ff974961711afe9514a91e16934b5f541 Mon Sep 17 00:00:00 2001 From: Milana Cap Date: Wed, 24 Jun 2026 16:33:49 +0200 Subject: [PATCH 2/6] Fix yml formatting for CI. Signed-off-by: Milana Cap --- .github/workflows/test-deploy.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/test-deploy.yml b/.github/workflows/test-deploy.yml index 56862b9..f58ad60 100644 --- a/.github/workflows/test-deploy.yml +++ b/.github/workflows/test-deploy.yml @@ -29,10 +29,10 @@ jobs: fetch-depth: 0 - name: Checkout TSC faqs - uses: actions/checkout@v4 - with: - repository: fairpm/tsc - path: external/tsc/faq + uses: actions/checkout@v4 + with: + repository: fairpm/tsc + path: external/tsc/faq - uses: actions/setup-node@v4 with: From 18a9fca9ea01a3c52138ef1d29e927f491d091cb Mon Sep 17 00:00:00 2001 From: Milana Cap Date: Wed, 24 Jun 2026 16:45:39 +0200 Subject: [PATCH 3/6] Change path and add debugging output for CI workflow. Signed-off-by: Milana Cap --- .github/workflows/test-deploy.yml | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/.github/workflows/test-deploy.yml b/.github/workflows/test-deploy.yml index f58ad60..f259f90 100644 --- a/.github/workflows/test-deploy.yml +++ b/.github/workflows/test-deploy.yml @@ -32,7 +32,22 @@ jobs: uses: actions/checkout@v4 with: repository: fairpm/tsc - path: external/tsc/faq + path: docs/external/tsc/ + + - name: Debug checked out files + run: | + echo "GITHUB_WORKSPACE=$GITHUB_WORKSPACE" + echo "Current directory:" + pwd + echo "Repo root:" + ls -la "$GITHUB_WORKSPACE" + echo "Docs root:" + ls -la "$GITHUB_WORKSPACE/docs" + echo "External:" + find "$GITHUB_WORKSPACE/docs/external" -maxdepth 5 -type d -print || true + echo "Expected folder:" + ls -la "$GITHUB_WORKSPACE/docs/external/tsc/faq" || true + working-directory: . - uses: actions/setup-node@v4 with: From fe5b57994bc8bbf472a33c9ebe8d61290d87c866 Mon Sep 17 00:00:00 2001 From: Milana Cap Date: Wed, 24 Jun 2026 16:55:02 +0200 Subject: [PATCH 4/6] Fix typo :rolleyes: Signed-off-by: Milana Cap --- .github/workflows/test-deploy.yml | 2 +- docs/plugins.js | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/test-deploy.yml b/.github/workflows/test-deploy.yml index f259f90..b801234 100644 --- a/.github/workflows/test-deploy.yml +++ b/.github/workflows/test-deploy.yml @@ -46,7 +46,7 @@ jobs: echo "External:" find "$GITHUB_WORKSPACE/docs/external" -maxdepth 5 -type d -print || true echo "Expected folder:" - ls -la "$GITHUB_WORKSPACE/docs/external/tsc/faq" || true + ls -la "$GITHUB_WORKSPACE/docs/external/tsc/faqs" || true working-directory: . - uses: actions/setup-node@v4 diff --git a/docs/plugins.js b/docs/plugins.js index cd5e13c..0b05202 100644 --- a/docs/plugins.js +++ b/docs/plugins.js @@ -6,7 +6,7 @@ const plugins = [ '@docusaurus/plugin-content-docs', { id: 'tsc', - path: 'external/tsc/faq', + path: 'external/tsc/faqs', routeBasePath: 'tsc', sidebarPath: require.resolve('./sidebars-tsc.js'), editUrl: ({docPath}) => From ceb14b30710f1c6ad141808b4766c2e2699c1c63 Mon Sep 17 00:00:00 2001 From: Milana Cap Date: Wed, 24 Jun 2026 16:59:51 +0200 Subject: [PATCH 5/6] Don't stop build on broken links, just log them. External repositories might have broken ones. Signed-off-by: Milana Cap --- docs/docusaurus.config.js | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/docusaurus.config.js b/docs/docusaurus.config.js index c887aeb..fe160e5 100644 --- a/docs/docusaurus.config.js +++ b/docs/docusaurus.config.js @@ -32,7 +32,8 @@ const config = { projectName: 'docs', deploymentBranch: 'gh-pages', - onBrokenLinks: 'throw', + // onBrokenLinks: 'throw', + onBrokenLinks: 'log', // Even if you don't use internationalization, you can use this field to set // useful metadata like html lang. For example, if your site is Chinese, you From 0829473689206d7962013dae8ecd711990b3ba7f Mon Sep 17 00:00:00 2001 From: Milana Cap Date: Wed, 24 Jun 2026 17:04:22 +0200 Subject: [PATCH 6/6] Add external repo to deploy workflow. Signed-off-by: Milana Cap --- .github/workflows/deploy.yml | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 6b9125f..0d00191 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -6,7 +6,7 @@ on: - main # Allow running this workflow manually from the Actions tab workflow_dispatch: - + defaults: run: shell: bash @@ -24,6 +24,12 @@ jobs: with: fetch-depth: 0 + - name: Checkout TSC faqs + uses: actions/checkout@v4 + with: + repository: fairpm/tsc + path: docs/external/tsc/ + - uses: actions/setup-node@v4 with: node-version: 20