mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-11-10 18:50:52 +03:00
ee846db056
[Preview link](https://marion-docs-restructure.hasura-docs-mono.pages.dev/docs/latest/index/) This PR is a complete restructure of documentation including the following: - Merge [core](https://hasura.io/docs/latest/graphql/core/index/) and [cloud](https://hasura.io/docs/latest/graphql/cloud/index/) docs - Integrate [enterprise](https://docs.ee.hasura.io/) docs - Flip [database section](https://hasura.io/docs/latest/graphql/core/databases/index/) - Much more @robertjdominguez @seanparkross please add improvements and link to the sections that you've updated, so that it's easy to find for reviewers. PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4882 Co-authored-by: surendran82 <26085612+surendran82@users.noreply.github.com> Co-authored-by: Abby Sassel <3883855+sassela@users.noreply.github.com> Co-authored-by: Sean Park-Ross <94021366+seanparkross@users.noreply.github.com> Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com> Co-authored-by: Rikin Kachhia <54616969+rikinsk@users.noreply.github.com> GitOrigin-RevId: 897191003a5e20dcc525b15e571725a34dc7d76e
309 lines
8.5 KiB
Plaintext
309 lines
8.5 KiB
Plaintext
---
|
|
sidebar_label: Page Structure
|
|
---
|
|
|
|
# Docs page structure
|
|
|
|
## Meta information
|
|
|
|
The following meta information should be added at the beginning of each docs page: `description` and `keywords`.
|
|
|
|
An example:
|
|
|
|
```markdown
|
|
---
|
|
description: Data validations in Hasura
|
|
keywords:
|
|
- hasura
|
|
- docs
|
|
- schema
|
|
- data validation
|
|
---
|
|
```
|
|
|
|
## React component imports
|
|
|
|
Please add any React component imports right below the frontmatter and before starting the main doc content.
|
|
|
|
```jsx
|
|
import Thumbnail from '@site/src/components/Thumbnail';
|
|
```
|
|
|
|
Note: When importing components from `src/` directory, please do not use relative paths. Docusaurus provides a global
|
|
variable `@site` which is resolved to root of app - absolute import. So, doing `@site/src/components/Thumbnail` is same
|
|
as `../../../src/components/Thumbnail`.
|
|
|
|
## Page title
|
|
|
|
Add the main title for each docs page.
|
|
|
|
An example:
|
|
|
|
```
|
|
# Data validations
|
|
```
|
|
|
|
You can also add `title` frontmatter.
|
|
|
|
```markdown
|
|
---
|
|
title: Data validations
|
|
---
|
|
```
|
|
|
|
By default the title will be the label for sidebar item. So, to use a shorten/different label for sidebar use the
|
|
`sidebar_label` frontmatter to override.
|
|
|
|
## Table of contents
|
|
|
|
This is auto generated on the right sidebar. And the depth can be controlled via `toc_max_heading_level`,
|
|
`toc_min_heading_level` frontmatter.
|
|
|
|
Please refer [Table of Contents](/rst-vs-mdx-guide/table-of-contents.mdx) section to understand more about hwo to render
|
|
this manually in between content and filtering items etc.,
|
|
|
|
## Introduction
|
|
|
|
Add an `Introduction` section:
|
|
|
|
```
|
|
## Introduction
|
|
```
|
|
|
|
In the section, give a short overview of what the page is about.
|
|
|
|
## General guidelines
|
|
|
|
### Content
|
|
|
|
- Add appropriate cross-links in content to assist users. i.e. if you refer to some functionality that is documented in
|
|
some other docs page, add a link to that page. e.g. if you have a statement like "create a relationship between tables
|
|
X and Y ...", make "create a relationship" a link to the `Create relationships` page.
|
|
- Try to make each section within a page self-sufficient. i.e. avoid structuring all pages as step-by-step guides unless
|
|
it really is the intent. This ensures that we can refer to sections externally (from other docs pages, console, etc.)
|
|
and expect that the user will be able to follow the section without being lost on the context that was set in earlier
|
|
sections of the page. Adding statements such as "As we have described in the above section ..." might help to set up
|
|
the needed context.
|
|
|
|
### Header section
|
|
|
|
- Page titles should be self-sufficient. Users might not have the context of the hierarchy of the page in the docs tree.
|
|
A user can land on a page via search as well. e.g. Say you are adding a new deployment guide for AWS under
|
|
`Guides -> Deployment -> AWS`. The title of this page should not be just `AWS` but instead
|
|
`AWS deployment guide for Hasura GraphQL engine`. It's ok to alias it to just `AWS` in the sidebar
|
|
(`sidebar_label: AWS`) as there the user has the context of the page hierarchy.
|
|
- Ensure heading underlines are the same length as the headings. Short underlines will throw warnings during builds.
|
|
- Use bold in headings in place of string literals for aesthetics (i.e. \*\* in place of \`).
|
|
- The nesting of headings is as follows:
|
|
|
|
```
|
|
# Main page title
|
|
|
|
## First heading
|
|
|
|
### Second heading
|
|
|
|
#### Third heading
|
|
|
|
##### Fourth heading
|
|
|
|
###### Fifth heading
|
|
```
|
|
|
|
### References / links
|
|
|
|
#### Internal links
|
|
|
|
When linking to other docs pages, use _root relative file paths_ (`/schema/postgres/tables.mdx`) rather than _relative
|
|
links_ (`../../path/to/file.mdx`) in order to avoid broken links. Why? when files are moved around, we just need to
|
|
replace old path with new path - no relative `../../../` resolution required.
|
|
|
|
Please read the [Links](/rst-vs-mdx-guide/links.mdx) section for more details on how to work with Links.
|
|
|
|
An example:
|
|
|
|
```
|
|
[Postgres tables](/schema/postgres/tables.mdx)
|
|
```
|
|
|
|
In this example, `Postgres tables` is the link text, and `/schema/postgres/tables.mdx` is the file path which will be
|
|
resolved as link by docusaurus.
|
|
|
|
#### External links
|
|
|
|
External links are no different in syntax, replace the file paths with external links and that's it.
|
|
|
|
An example:
|
|
|
|
`[Google](https://www.google.com/)` [Google](https://www.google.com/)
|
|
|
|
_Note_: If you link to an external resource, make sure to link to the most current version of the same, e.g.
|
|
`https://www.postgresql.org/docs/current/intro-whatis.html` rather than
|
|
`https://www.postgresql.org/docs/9.6/intro-whatis.html`.
|
|
|
|
### Images
|
|
|
|
Add images using the `Thumbnail` component to allow click-to-zoom.
|
|
|
|
An example:
|
|
|
|
```jsx
|
|
import Thumbnail from '@site/src/components/Thumbnail';
|
|
|
|
<Thumbnail
|
|
src='/img/graphql/manual/schema/validation-add-check-constraint.png'
|
|
alt='Add check constraint'
|
|
width='700px'
|
|
/>;
|
|
```
|
|
|
|
- Add an `alt` prop for all images
|
|
- To adjust the image size, use the `width` prop
|
|
|
|
#### Style elements for emphasizing
|
|
|
|
If you have screenshots in your docs page and you want to emphasize something, please use this colour code: `#ec1c74`.
|
|
|
|
Generally, if you want to show selecting something, use borders. If you want to show clicking on a button, use arrows.
|
|
|
|
### Notes / Admonitions
|
|
|
|
A note can be added in order to draw attention to something like limitations or to link to external reference
|
|
documentation. It has the title "Notes".
|
|
|
|
An example:
|
|
|
|
```
|
|
|
|
:::info Note
|
|
|
|
Please checkout the [Postgres documentation](https://www.postgresql.org/docs/current/functions-comparison.html) for more information.
|
|
|
|
:::
|
|
|
|
```
|
|
|
|
An admonition is the same as a note, but its title can be defined.
|
|
|
|
Add an admonition as follows:
|
|
|
|
```
|
|
:::info Other Title
|
|
|
|
Scheduled triggers are supported by `v.1.3.0` and above.
|
|
|
|
:::
|
|
|
|
:::tip Supported by
|
|
|
|
Scheduled triggers are supported by `v.1.3.0` and above.
|
|
|
|
:::
|
|
|
|
:::caution Deprecation
|
|
|
|
Scheduled triggers are supported by `v.1.3.0` and above.
|
|
|
|
:::
|
|
|
|
:::danger Security Vulnerability
|
|
|
|
Scheduled triggers are supported by `v.1.3.0` and above.
|
|
|
|
:::
|
|
|
|
```
|
|
|
|
_Note_: Make sure to leave an intentional empty line before and after each `:::` in admonitions - beginning and end
|
|
both.
|
|
|
|
```diff {1,3,5,7}
|
|
+
|
|
:::info Note
|
|
+
|
|
Make sure to place the note/admonition in a place where the user will see it at the appropriate time.
|
|
+
|
|
:::
|
|
+
|
|
```
|
|
|
|
_Note_: Make sure to place the note/admonition in a place where the user will see it at the appropriate time.
|
|
|
|
### Code blocks
|
|
|
|
While adding code blocks ensure the right language type is set. Sometimes adding placeholders breaks the language's
|
|
syntax in which case you'll have to set the language type to `none` to avoid warnings during builds.
|
|
|
|
### GraphQL request examples
|
|
|
|
Our docs have a GraphiQL extension that allows displaying GraphQL requests in the GraphiQL UI.
|
|
|
|
- Use a tab-width of 2 for nesting the requests and responses for optimal use of the space and maintaining consistency.
|
|
- Nest query arguments for logical readability. Unfortunately, GraphiQL prettify does not do a good job of doing this by
|
|
default.
|
|
- Ensure that the order of fields in the responses is the same as in the requests for better readability.
|
|
|
|
Use it as follows:
|
|
|
|
```jsx
|
|
import GraphiQLIDE from '@site/src/components/GraphiQLIDE';
|
|
|
|
<GraphiQLIDE
|
|
query={`query {
|
|
author_by_pk(id: 1) {
|
|
id
|
|
name
|
|
}
|
|
}`}
|
|
response={`{
|
|
"data": {
|
|
"author_by_pk": {
|
|
"id": 1,
|
|
"name": "Justin"
|
|
}
|
|
}
|
|
}`}
|
|
/>;
|
|
```
|
|
|
|
You dont have to worry about indentation when adding components for better spacing in string literals
|
|
|
|
## Markdown Variables
|
|
|
|
Add the markdown variables at very end of file for easier reference and maintainability. These variables are mostly for
|
|
links. To avoid repetition of adding full path for each link, we could take advantage of
|
|
[reference-style-links](https://daringfireball.net/projects/markdown/syntax#link) syntax in markdown.
|
|
|
|
For Example:
|
|
|
|
```markdown
|
|
## Section one
|
|
|
|
.....
|
|
|
|
REST ... [create_action][metadata-create-action] or [update_action][metadata-update-action] metadata APIs ...
|
|
[request_transform][requesttransformation] field ...:
|
|
|
|
....
|
|
|
|
## Section two
|
|
|
|
.....
|
|
|
|
REST ... [create_action][metadata-create-action] or [update_action][metadata-update-action] metadata APIs ...
|
|
[request_transform][requesttransformation] field ...:
|
|
|
|
....
|
|
|
|
<!-- Shared Link Variables -->
|
|
|
|
[metadata-create-action]: /api-reference/metadata-api/actions.mdx#metadata-create-action
|
|
[metadata-update-action]: /api-reference/metadata-api/actions.mdx#metadata-update-action
|
|
[requesttransformation]: /api-reference/syntax-defs.mdx#requesttransformation
|
|
```
|
|
|
|
## Run docs build
|
|
|
|
Run the docs build in the end again with `yarn build` and make sure there are no errors/warnings because of any
|
|
inconsitencies etc.
|