mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-09-19 06:28:39 +03:00
96646005f7
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/7715 Co-authored-by: Sean Park-Ross <94021366+seanparkross@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> GitOrigin-RevId: 61a91af22333ef08db1ec623941ac9dd5dc50179
147 lines
4.7 KiB
Plaintext
147 lines
4.7 KiB
Plaintext
---
|
|
sidebar_position: 70
|
|
---
|
|
|
|
# Working with Docusaurus
|
|
|
|
If you're interested in a deep dive on Docusaurus and how it works, check out [their docs](https://docusaurus.io/docs).
|
|
This page is intended to serve as a crash course on common conventions within Docusaurus and how they apply to Hasura's
|
|
docs 🤙
|
|
|
|
:::info Guides
|
|
|
|
Also checkout their [Guides](https://docusaurus.io/docs/category/guides), they are pretty detailed.
|
|
|
|
Please check the [Advanced Guides](https://docusaurus.io/docs/advanced) to learn in depth about Architecture, Plugins,
|
|
Routing etc.
|
|
|
|
:::
|
|
|
|
## docusaurus.config.js
|
|
|
|
All the magic happens here. [SEO](https://docusaurus.io/docs/seo), [Theme](https://docusaurus.io/docs/api/themes),
|
|
[Plugins](https://docusaurus.io/docs/api/plugins), [Navbar](https://docusaurus.io/docs/api/themes/configuration#navbar),
|
|
[Footer](https://docusaurus.io/docs/api/themes/configuration#footer-1),
|
|
[Search Config](https://docusaurus.io/docs/search#using-algolia-docsearch), and
|
|
[what not...](https://docusaurus.io/docs/category/guides)
|
|
|
|
Please check the [API for all possible config options here](https://docusaurus.io/docs/api/docusaurus-config).
|
|
|
|
## Cleint API - components, hooks etc.
|
|
|
|
Please check the [client API docs](https://docusaurus.io/docs/docusaurus-core) for available React components, hooks &
|
|
modules.
|
|
|
|
## Sidebar
|
|
|
|
### Label & position
|
|
|
|
**For Individual Files**
|
|
|
|
Use of `sidebar_label` and `sidebar_position` frontmatter
|
|
|
|
```markdown title=graphql/core/actions/create.mdx
|
|
---
|
|
sidebar_label: Creating actions
|
|
sidebar_position: 1
|
|
---
|
|
```
|
|
|
|
**For Directories (Categories)**
|
|
|
|
By default, index.mdx doc's - `sidebar_label` & `sidebar_position` will be applied for directories.
|
|
|
|
To override, please add a `_category_.json` and add the `label` and `position` properties.
|
|
|
|
```json title=graphql/core/actions/_category_.json
|
|
{
|
|
"label": "Actions",
|
|
"position": 3
|
|
}
|
|
```
|
|
|
|
:::info More about Sidebar
|
|
|
|
You can also create a custom sidebar and add everthing manually.
|
|
|
|
Checkout Docusaurus Docs for Sidebar - https://docusaurus.io/docs/sidebar
|
|
|
|
:::
|
|
|
|
### index.mdx file only directories
|
|
|
|
This is known and default behavior from docusaurus. `index` is considered direct link to directory index and won't be
|
|
visible unless there is one more file.
|
|
|
|
If you only have an index.mdx file, prefer `directory.mdx` over `directory/index.mdx`.
|
|
|
|
## URL slug
|
|
|
|
This only applies for index.mdx files.
|
|
|
|
index file routes are resolved to `directory/` and not `directory/index`
|
|
|
|
Use `slug` Metadata to manually set the slug to `index`. Please check
|
|
[this PR on docusaurus](https://github.com/facebook/docusaurus/pull/5830) for more information.
|
|
|
|
```markdown title="graphql/core/actions/overview.mdx"
|
|
---
|
|
slug: index
|
|
---
|
|
```
|
|
|
|
## Styling
|
|
|
|
The majority of styles is controlled through CSS variables - there is a heavy list available (use the browser inspect
|
|
element to see the complete list).
|
|
|
|
These variables can be overridden and new custom styles to be added in `src/css/custom.scss` and
|
|
`src/css/_custom-dark.scss` for light and dark themes respectively.
|
|
|
|
## React components
|
|
|
|
Add any new React Components to the `src/components/ComponentName` directory. Add the `index.tsx` file and use
|
|
`styles.module.scss` for styling to not let this collide with global styles.
|
|
|
|
Then this component can be imported with `@site` global directive.
|
|
|
|
`import ComponentName from '@site/src/components/ComponentName';`
|
|
|
|
:::tip
|
|
|
|
Check existing components for a better idea.
|
|
|
|
:::
|
|
|
|
## Static assets
|
|
|
|
All the static assets lives in `static` directory.
|
|
|
|
| Asset | Directory |
|
|
| ------ | -------------- |
|
|
| Images | `static/img` |
|
|
| Fonts | `static/fonts` |
|
|
| Icons | `static/icons` |
|
|
|
|
## Updating to latest Docusaurus version
|
|
|
|
Checkout the change log for latest releases and changes involved - https://docusaurus.io/changelog/
|
|
|
|
Please ensure to check breaking changes and re-swizzle any swizzled components given they are part of breaking changes.
|
|
|
|
Any [swizzled](https://docusaurus.io/docs/swizzling) component will be cloned to `src/theme`.
|
|
|
|
**An Example:** The `TOCInline` and `TOCItems` components are [swizzled](https://docusaurus.io/docs/swizzling) and
|
|
custom logic is added.
|
|
|
|
The custom added logic (`src/theme/TOCInline`, `src/theme/TOCItems`) is indicated by comments - `// Customization START`
|
|
and `// Customization END`. If reswizzled in the future, only these blocks need an update.
|
|
|
|
[`toc` is a flat array](https://docusaurus.io/docs/markdown-features/inline-toc#custom-table-of-contents) and has no
|
|
concept of nested tree children structure. This behavior is changed in `2.0.0-beta.16`. Please check the
|
|
[Breaking changes that forced us to swizzle](https://docusaurus.io/changelog/2.0.0-beta.16#-breaking-change).
|
|
|
|
## Docusaurus Support
|
|
|
|
[Join their Discord](https://discordapp.com/invite/docusaurus) and ask in `#help-and-questions`
|