mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
cc30f08f6e
PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4261 GitOrigin-RevId: 3d80068acdd61b5350fc36ec3444db47508f9c09
138 lines
4.5 KiB
Plaintext
138 lines
4.5 KiB
Plaintext
# Working with Docusaurus
|
|
|
|
Whats better place than the [Docusaurus docs](https://docusaurus.io/docs) site itself?
|
|
|
|
:::info Guides
|
|
|
|
Also checkout the [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 [clent 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/index.mdx"
|
|
---
|
|
slug: index
|
|
---
|
|
```
|
|
|
|
## Styling
|
|
|
|
Majority of styles is controlled through css variables - there is a heavy list available (use 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 `src/components/ComponentName` directory. Add `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 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`
|