Repository navigation
feat: migrate documentation site to Docusaurus #60
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
Show all changes
2 commits
Select commit
Hold shift + click to select a range
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,28 +1,15 @@ | ||
| # Welcome | ||
| --- | ||
| slug: / | ||
| --- | ||
|
|
||
| ocular is a set of tools to help build and publish open source frameworks. It contains: | ||
| - a `dev-tools` module that installs and provides base configurations for tools such as Biome, Vite, esbuild and lerna. | ||
| - a `gatsby-theme-ocular` module that contains a markdown to HTML converter to make it easy to build websites. | ||
| ## About ocular-dev-tools | ||
| # vis.gl development tools | ||
|
|
||
| ocular-dev-tools installs a set of configurable development scripts to handle build, test and publish tasks for JavaScript framework repositories. | ||
| Shared development tools for building, testing, linting, bundling, and publishing vis.gl's open source JavaScript frameworks. | ||
|
|
||
| While highly configurable ocular-dev-tools is very opinionated in choice of tooling etc, and mainly targets vis.gl frameworks, like deck.gl, luma.gl etc. | ||
| ## Documentation | ||
|
|
||
| ## About gatsby-theme-ocular | ||
| - [Dev tools](/docs/dev-tools) — build, test, lint, release, and migration guidance. | ||
| - [TypeScript plugins](/docs/ts-plugins/ts-transform-webgpu) — TypeScript transforms maintained by this repository. | ||
| - [Docusaurus Website](./docusaurus-website.md) — the shared documentation website package used by current vis.gl projects. | ||
|
|
||
| The vis.gl team needed a system to build documentation websites with the least amount of friction. Our first use case has been the websites for the various visualization projects such as [deck.gl](https://deck.gl) [luma.gl](https://luma.gl) or [loaders.gl](https://loaders.gl). | ||
|
|
||
| We wanted: | ||
| - to organize documentation files with a table of contents, navigation and search; | ||
| - to have interactive examples; | ||
| - to have some control on formatting; | ||
| - to generate websites discoverable by search engines; | ||
| - to make it easy to publish these websites, especially on github pages; | ||
| - to make this experience possible without writing a line of code; | ||
| - to provide sensible defaults in terms of navigation and styling; | ||
| - but to allow advanced users to overwrite and customize anything they want. | ||
|
|
||
| Happy documenting! | ||
|
|
||
| To find out more, go to [get started](get-started.md) | ||
| The documentation site is built with Docusaurus and the shared `@vis.gl/docusaurus-website` configuration. | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| --- | ||
| title: Docusaurus Website | ||
| --- | ||
|
|
||
| # Docusaurus Website | ||
|
|
||
| `@vis.gl/docusaurus-website` provides shared Docusaurus components and configuration for vis.gl's open source JavaScript frameworks. | ||
|
|
||
| The package supplies the common vis.gl and OpenJS branding, navigation, footer, local search, stylesheet, and webpack behavior used by project documentation sites. The implementation and tests are in [`modules/docusaurus-website`](https://github.com/visgl/dev-tools/tree/master/modules/docusaurus-website). | ||
|
|
||
| Project sites typically create a small `docusaurus.config.js` and call `getDocusaurusConfig` with the project name, repository URL, canonical site URL, and documentation table of contents. | ||
|
|
||
| This package replaces the former Gatsby-based `gatsby-theme-ocular` website tooling. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| title: Historical Gatsby documentation | ||
| --- | ||
|
|
||
| # Historical Gatsby documentation | ||
|
|
||
| Earlier versions of this project included a Gatsby theme named `gatsby-theme-ocular`. That theme and its website-specific documentation are no longer part of the repository. | ||
|
|
||
| Current vis.gl project sites use Docusaurus with `@vis.gl/docusaurus-website`. See the [Docusaurus Website guide](./docusaurus-website.md) for the current approach. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,167 +1,5 @@ | ||
| { | ||
| "id": "table-of-contents", | ||
| "chapters": [ | ||
| { | ||
| "title": "Overview", | ||
| "entries": [ | ||
| { | ||
| "entry": "docs" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "ocular-dev-tools", | ||
| "chapters": [ | ||
| { | ||
| "title": "Overview", | ||
| "entries": [ | ||
| { | ||
| "entry": "modules/dev-tools/docs/" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/whats-new" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/upgrade-guide" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/faq" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "Configuration Guide", | ||
| "entries": [ | ||
| { | ||
| "entry": "modules/dev-tools/docs/" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/developer-guide/command-line-interface" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/developer-guide/configuring-tests" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/developer-guide/aliases" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "Command Line Reference", | ||
| "entries": [ | ||
| { | ||
| "entry": "modules/dev-tools/docs/cli/ocular-bootstrap" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/cli/ocular-build" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/cli/ocular-clean" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/cli/ocular-lint" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/cli/ocular-test" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/cli/ocular-metrics" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/cli/ocular-publish" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/cli/ocular-bump" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "API Reference", | ||
| "entries": [ | ||
| { | ||
| "entry": "modules/dev-tools/docs/api-reference/get-babel-config" | ||
| }, | ||
| { | ||
| "entry": "modules/dev-tools/docs/api-reference/get-webpack-config" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "gatsby-theme-ocular", | ||
| "chapters": [ | ||
| { | ||
| "title": "Overview", | ||
| "entries": [ | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/get-started" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/whats-new" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/upgrade-guide" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "Creating content", | ||
| "entries": [ | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/get-started" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/whats-new" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/upgrade-guide" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "Creating content", | ||
| "entries": [ | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/creating-content/writing-documentation" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/creating-content/interactive-examples" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "Developer Guide", | ||
| "entries": [ | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/developer-guide/configuring" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/developer-guide/deploying" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/developer-guide/debugging" | ||
| } | ||
| ] | ||
| }, | ||
| { | ||
| "title": "API Reference", | ||
| "entries": [ | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/api-reference/options" | ||
| }, | ||
| { | ||
| "entry": "modules/gatsby-theme-ocular/docs/api-reference/generated-pages" | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| ] | ||
| } | ||
| [ | ||
| "README", | ||
| {"type": "category", "label": "Docusaurus Website", "items": ["docusaurus-website"]}, | ||
| {"type": "category", "label": "Historical: Gatsby Ocular", "items": ["legacy-gatsby"]} | ||
|
ibgreen marked this conversation as resolved.
|
||
| ] | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| const {resolve} = require('path'); | ||
| const {getDocusaurusConfig} = require('@vis.gl/docusaurus-website'); | ||
|
|
||
| const config = getDocusaurusConfig({ | ||
| projectName: 'dev-tools', | ||
| tagline: 'Shared development tools for vis.gl projects', | ||
| siteUrl: 'https://visgl.github.io/dev-tools/', | ||
| repoUrl: 'https://github.com/visgl/dev-tools', | ||
| docsTableOfContents: require('../docs/table-of-contents.json'), | ||
| search: 'local', | ||
| plugins: [ | ||
| ['@docusaurus/plugin-content-docs', { | ||
| id: 'dev-tools', | ||
| path: resolve(__dirname, '../modules/dev-tools/docs'), | ||
| routeBasePath: 'docs/dev-tools', | ||
| sidebarPath: resolve(__dirname, './src/sidebars/dev-tools.js'), | ||
| breadcrumbs: false, | ||
| editUrl: 'https://github.com/visgl/dev-tools/tree/master/modules/dev-tools/docs/' | ||
| }], | ||
| ['@docusaurus/plugin-content-docs', { | ||
| id: 'ts-plugins', | ||
| path: resolve(__dirname, '../modules/ts-plugins/docs'), | ||
| routeBasePath: 'docs/ts-plugins', | ||
| sidebarPath: resolve(__dirname, './src/sidebars/ts-plugins.js'), | ||
| breadcrumbs: false, | ||
| editUrl: 'https://github.com/visgl/dev-tools/tree/master/modules/ts-plugins/docs/' | ||
| }], | ||
| ['@docusaurus/plugin-client-redirects', { | ||
| redirects: [ | ||
| {from: '/about', to: '/docs'}, | ||
| {from: '/docs/ocular-dev-tools', to: '/docs/dev-tools'}, | ||
| {from: '/docs/gatsby-theme-ocular', to: '/docs/legacy-gatsby'}, | ||
| {from: '/ocular-dev-tools', to: '/docs/dev-tools'}, | ||
| {from: '/gatsby-theme-ocular', to: '/docs/legacy-gatsby'} | ||
| ] | ||
| }] | ||
| ] | ||
| }); | ||
|
|
||
| config.baseUrl = process.env.WEBSITE_BASE_URL || '/dev-tools/'; | ||
|
|
||
| module.exports = config; |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.