diff --git a/docs/src/pages/index.tsx b/docs/src/pages/index.tsx index 6aade371fe2..018d98ef425 100644 --- a/docs/src/pages/index.tsx +++ b/docs/src/pages/index.tsx @@ -27,7 +27,7 @@ function HomepageHeader() {
- + Docs Style Guide
diff --git a/docs/wiki/checklist.mdx b/docs/wiki/checklist.mdx index 6e5149588fc..1945802f7dc 100644 --- a/docs/wiki/checklist.mdx +++ b/docs/wiki/checklist.mdx @@ -1,6 +1,6 @@ --- sidebar_label: PR Review Checklist -sidebar_position: 7 +sidebar_position: 30 --- # PR Checklist @@ -36,9 +36,10 @@ contributions. ## Pass two: infrastructure Next, we'll typically do an infrastructure test (i.e., does everything 'work'?). If you followed the guidelines in our -[style guide](/style/index.mdx), you're probably okay. However, we'll also do the following: +[style guide](/wiki/category/style/), you're probably okay. However, we'll also do the following: -- Check new internal links and ensure they're [root-relative file paths](/page-structure.mdx#references--links) +- Check new internal links and ensure they're + [root-relative file paths](/docusaurus-mdx-guide/page-structure.mdx#references--links) - Check external links and ensure they're not returning `404` - Double-check headings are [correctly cased](/style/headings.mdx) - Look for Hasura features (like Hasura Console, Metadata, Migrations) and ensure they're proper cases diff --git a/docs/wiki/contributions.mdx b/docs/wiki/contributions.mdx index c7461aa6275..ce51a733283 100644 --- a/docs/wiki/contributions.mdx +++ b/docs/wiki/contributions.mdx @@ -147,7 +147,7 @@ yarn start ### Step 3: Make your local changes -We have a [comprehensive-yet-continually-evolving style guide](/style/index.mdx). We ask that you reference it as you +We have a [comprehensive-yet-continually-evolving style guide](/wiki/category/style/). We ask that you reference it as you begin formatting your docs contribution. If you don't want to go piece-by-piece in the style guide, find a page of documentation you think works well and use it diff --git a/docs/wiki/docusaurus-mdx-guide/_category_.json b/docs/wiki/docusaurus-mdx-guide/_category_.json new file mode 100644 index 00000000000..87d92ebc9b2 --- /dev/null +++ b/docs/wiki/docusaurus-mdx-guide/_category_.json @@ -0,0 +1,8 @@ +{ + "label": "Docusaurus MDX Guide", + "position": 40, + "link": { + "type": "generated-index", + "title": "Docusaurus Markdown Guide Index" + } +} diff --git a/docs/wiki/rst-vs-mdx-guide/admonitions.mdx b/docs/wiki/docusaurus-mdx-guide/admonitions.mdx similarity index 50% rename from docs/wiki/rst-vs-mdx-guide/admonitions.mdx rename to docs/wiki/docusaurus-mdx-guide/admonitions.mdx index 9b5a6087a2f..3b08f365665 100644 --- a/docs/wiki/rst-vs-mdx-guide/admonitions.mdx +++ b/docs/wiki/docusaurus-mdx-guide/admonitions.mdx @@ -3,46 +3,30 @@ import TabItem from '@theme/TabItem'; # Admonitions - - - -```rest - .. note:: - - **Adding an additional layer on top of the Hasura GraphQL engine significantly impacts the performance provided by - it out of the box** (*by as much as 4x*). If you need any help with remodelling these kinds of use cases to use the - built-in remote schemas feature, please get in touch with us on `Discord `__. - - .. admonition:: Additional Resources - - Data Federation with Hasura - `Watch Webinar `__. -``` - - - - +Call-out admonitions allow you to highlight parts of the documentation which require special attention or which +don't fit in the usual flow of content. ```markdown :::note -**Adding an additional layer on top of the Hasura GraphQL engine significantly impacts the performance provided by -it out of the box** (*by as much as 4x*). If you need any help with remodelling these kinds of use cases to use the -built-in remote schemas feature, please get in touch with us on [Discord](https://discord.gg/vBPpJkS). +**This** is an example of a call-out admonition. For more info please get in touch with us on [Discord] +(https://discord.gg/vBPpJkS). ::: +``` +```markdown :::note Additional Resources Data Federation with Hasura - [Watch Webinar](https://hasura.io/events/webinar/data-federation-hasura-graphql/). ::: - - ``` :::caution Please note the empty lines -Please ensure to leave empty lines in the start and the end (first and last lines). This is due to avoid prettier messing up the formatting as this is docusaurus special syntax. +Please ensure to leave empty lines in the start and the end (first and last lines). This to avoid prettier messing +up the formatting in this Docusaurus special syntax. Read about it on the [Docusaurus Docs](https://docusaurus.io/docs/markdown-features/admonitions#usage-with-prettier) @@ -59,9 +43,6 @@ Make sure to place the note/admonition in a place where the user will see it at ``` - - - which would render as below :::note @@ -84,6 +65,7 @@ Please prefer `:::info Note` over `:::note` for a decent blue colored note. :::info Note -For further syntax and usage reference please check docusaurus [Admonitions docs](https://docusaurus.io/docs/markdown-features/admonitions) +For further syntax and usage reference please check docusaurus +[Admonitions docs](https://docusaurus.io/docs/markdown-features/admonitions) ::: diff --git a/docs/wiki/rst-vs-mdx-guide/code-blocks.mdx b/docs/wiki/docusaurus-mdx-guide/code-blocks.mdx similarity index 50% rename from docs/wiki/rst-vs-mdx-guide/code-blocks.mdx rename to docs/wiki/docusaurus-mdx-guide/code-blocks.mdx index 0b52385d4ea..fa0c56c1e76 100644 --- a/docs/wiki/rst-vs-mdx-guide/code-blocks.mdx +++ b/docs/wiki/docusaurus-mdx-guide/code-blocks.mdx @@ -4,34 +4,18 @@ sidebar_position: 6 # Code Blocks -## Sphinx - RST - -```rest {1-2} -.. code-block:: graphql - :emphasize-lines: 2,5 - - query { - authors (where: {articles: {rating: {_gt: 4}}}) { - id - name - articles (where: {rating: {_gt: 4}}) { - id - title - rating - } - } - } -``` +While adding code blocks, ensure you set the correct language type. 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. ## Docusaurus - MDX ```markdown - // highlight-next-line ```graphql {2,5} query { + // highlight-next-line authors (where: {articles: {rating: {_gt: 4}}}) { id name + // highlight-next-line articles (where: {rating: {_gt: 4}}) { id title @@ -39,7 +23,6 @@ sidebar_position: 6 } } } - // highlight-next-line ``` ``` @@ -61,16 +44,20 @@ sidebar_position: 6 :::caution Supported Languages -- Docusaurus uses prisma under the hood for code-block syntax highlighting. Please refer to the supported languages [here](https://prismjs.com/#supported-languages). -- By default prisma includes a few that are listed [here](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js). If any supported language is not listed here, please added it to `additionalLanguages` under prisma plugin in `docusaurus.config.js` +- Docusaurus uses prisma under the hood for code-block syntax highlighting. Please refer to the supported languages +[here](https://prismjs.com/#supported-languages). +- By default prisma includes a few that are listed +[here](https://github.com/FormidableLabs/prism-react-renderer/blob/master/src/vendor/prism/includeLangs.js). If any +supported language is not listed here, please add it to `additionalLanguages` under prisma plugin in +`docusaurus.config.js`. ::: ## Parsed Literals -Sometimes we wanna add links within codeblocks, the triple tick (```) wont work in this case. - -Please use `pre` and `code` tags and use plain html within the `code`. To preserve indentation prefer string templates over `\n`, `\t` etc., +Sometimes we want to add links within codeblocks, the triple backtick syntax won't work in this case. Please use +`pre` and `code` tags and use plain html within the `code`. To preserve indentation prefer string templates +over `\n`, `\t` etc. ```html
@@ -88,8 +75,8 @@ Please use `pre` and `code` tags and use plain html within the `code`. To preser
Why is it wrapped in a div with parsed-literal className? -Using html + string templates is a workaround, if markdown ever supports this or provides an alternative, it would be easy to find the respective usage and replace it. -Nothing more :) +Using html + string templates is a workaround, if markdown ever supports this or provides an alternative, it would be +easy to find the respective usage and replace it. Nothing more :)
@@ -105,6 +92,7 @@ Nothing more :) :::tip -Please refer docusaurus [Code Blocks Docs](https://docusaurus.io/docs/markdown-features/code-blocks) for further syntax and usage guidance. +Please refer to docusaurus's [Code Blocks Docs](https://docusaurus.io/docs/markdown-features/code-blocks) for further syntax +and usage guidance. ::: diff --git a/docs/wiki/rst-vs-mdx-guide/graphiql-ide.mdx b/docs/wiki/docusaurus-mdx-guide/graphiql-ide.mdx similarity index 62% rename from docs/wiki/rst-vs-mdx-guide/graphiql-ide.mdx rename to docs/wiki/docusaurus-mdx-guide/graphiql-ide.mdx index 08b8e736c6a..56cd941fa8b 100644 --- a/docs/wiki/rst-vs-mdx-guide/graphiql-ide.mdx +++ b/docs/wiki/docusaurus-mdx-guide/graphiql-ide.mdx @@ -9,63 +9,37 @@ import GraphiQLIDE from '@site/src/components/GraphiQLIDE'; We use graphiql editor wherever applicable for example showcase throughout docs. -A `GraphiQLIDE` component is already created with required custom logic. So, use `GraphiQLIDE` just like any other React component. +A `GraphiQLIDE` component is already created with the required custom logic. So, use `GraphiQLIDE` just like any other +React component. -## Sphinx - RST +- 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. -```rest -// highlight-start -.. graphiql:: - :view_only: - :query: -// highlight-end - query get_authors_in_pincode ($jsonFilter: jsonb){ - authors( - where: { - address: {_contains: $jsonFilter } - } - ) { - id - name - address - } - } - // highlight-next-line - :response: - { - "data": { - "authors": [ - { - "id": 1, - "name": "Ash", - "address": { - "street_address": "161, 19th Main Road, Koramangala 6th Block", - "city": "Bengaluru", - "state": "Karnataka", - "pincode": 560095, - "phone": "9090909090", - } - } - ] - } - } - // highlight-next-line - :variables: - { - "jsonFilter": { - "pincode": 560095 - } +Use it as follows: + +```jsx +import GraphiQLIDE from '@site/src/components/GraphiQLIDE'; + +; ``` -:::note - -`:view_only:` is `viewOnly` prop and by default set to `true` in the `GraphQLIDE` component. - -::: - - -## Docusaurus - MDX ```jsx // highlight-start diff --git a/docs/wiki/rst-vs-mdx-guide/headings.mdx b/docs/wiki/docusaurus-mdx-guide/headings.mdx similarity index 62% rename from docs/wiki/rst-vs-mdx-guide/headings.mdx rename to docs/wiki/docusaurus-mdx-guide/headings.mdx index eb530b3ed1c..9d63963a046 100644 --- a/docs/wiki/rst-vs-mdx-guide/headings.mdx +++ b/docs/wiki/docusaurus-mdx-guide/headings.mdx @@ -10,25 +10,40 @@ import TabItem from '@theme/TabItem'; ## Headings -Please follow Good old `h1(#) => h6(######)` hierarchy. +Please follow good old `h1(#) => h6(######)` hierarchy. ```markdown -# Main page title +# This is the Main Page Title -## First heading +## This is a H2 heading -### Second heading +### This is a H3 heading -#### Third heading +#### This is a H4 heading -##### Fourth heading +##### This is a H5 heading -###### Fifth heading +###### This is a H6 heading ``` +Which renders out as: + +# This is the Main Page Title + +## This is a H2 Heading + +### This is a H3 Heading + +#### This is a H4 Heading + +##### This is a H5 Heading + +###### This is a H6 Heading + :::info Note -At any point of time there should only be one `h1` per doc. `h2 => h6` can be any number as required while ensuring correct hierarchy. +At any point of time there should only be one `h1` per doc. `h2 => h6` can be any number as required while ensuring +correct hierarchy. ::: @@ -60,9 +75,11 @@ To link to this section, we can append the id as a `#hash-param` to url. :::caution Handling changes to heading -This works as long as there is no change in the respective section heading. Updating the heading would require to scan through all the links that points to this section and update every time. +This works as long as there is no change in the respective section heading. Updating the heading would require +scanning all the links to this section and updating it every time. -So, to avoid this manual effort and making the links independeent, prefer adding a custom id while linking respective section. +So, to avoid this manual effort and making the links independent, prefer adding a custom id while linking respective +section. ::: @@ -74,38 +91,23 @@ Custom Heading Ids are added as `{#kebab-cased-id}` Prefer `lowercased-kebab-case` for all the ids to maintain consistency. - - - -```rest {1-4} -.. _create_hasura_project_aws_rds_aurora: - -Step 1: Create a Hasura Cloud project -------------------------------------- - -On the Hasura Cloud dashboard, create a new project: -``` - - - - ```markdown {1} ## Step 1: Create a Hasura Cloud project {#create-hasura-project-aws-rds-aurora} On the Hasura Cloud dashboard, create a new project: ``` - - - -They can also be generated when required using the cli command [write-heading-ids](https://docusaurus.io/docs/cli#docusaurus-write-heading-ids-sitedir) - Please DO NOT OVERRIDE exisiting ones). +They can also be generated when required using the cli command +[write-heading-ids](https://docusaurus.io/docs/cli#docusaurus-write-heading-ids-sitedir) - Please *DO NOT OVERRIDE* +existing ones. Skip for `h1 (#)` as the top level heading is beginining of file the direct link without `#hash-param` would work fine. :::danger Please do not add id in frontmatter -Docusaurus by default uses [file path (including folders) without the extension as the id](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#id) and the same will be slug. +Docusaurus by default uses [file path (including folders) without the extension as the id](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#id) +and the same will be slug. If an `id` is added in frontmatter the slug will by default be the id thus breaking the existing URL structure. @@ -117,4 +119,5 @@ In case, if you are not sure of what to do in a different situation. Please let ::: -> Please refer to docusaurus docs on [Headings](https://docusaurus.io/docs/markdown-features/headings) for more insights into usage and customization. \ No newline at end of file +Please refer to the Docusaurus docs on [Headings](https://docusaurus.io/docs/markdown-features/headings) for more +insights into usage and customization. \ No newline at end of file diff --git a/docs/wiki/docusaurus-mdx-guide/images.mdx b/docs/wiki/docusaurus-mdx-guide/images.mdx new file mode 100644 index 00000000000..1a8ecd58b57 --- /dev/null +++ b/docs/wiki/docusaurus-mdx-guide/images.mdx @@ -0,0 +1,23 @@ +--- +sidebar_position: 7 +sidebar_label: Images +--- + +# Images + +Add images using the `Thumbnail` component to allow click-to-zoom. + +An example: + +```jsx +import Thumbnail from '@site/src/components/Thumbnail'; + +; +``` + +- Add an `alt` prop for all images describing what the image contains. +- To adjust the image size, use the `width` prop. diff --git a/docs/wiki/rst-vs-mdx-guide/links.mdx b/docs/wiki/docusaurus-mdx-guide/links.mdx similarity index 63% rename from docs/wiki/rst-vs-mdx-guide/links.mdx rename to docs/wiki/docusaurus-mdx-guide/links.mdx index ad05571fd24..49ead9208c5 100644 --- a/docs/wiki/rst-vs-mdx-guide/links.mdx +++ b/docs/wiki/docusaurus-mdx-guide/links.mdx @@ -7,61 +7,22 @@ import TabItem from '@theme/TabItem'; # Links -Please refer [this](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html?highlight=links#hyperlinks) -to get familiar with links in Sphinx - ## External Links -These are straightforward syntax swap as given below. +`[Hasura Cloud](https://cloud.hasura.io/signup/)` - - - - `Hasura Cloud `_ - - - - - [Hasura Cloud](https://cloud.hasura.io/signup/) - - - ## Internal Links -Sphinx uses `:ref:` to simplify cross-referencing documents. You can read more about how it works in -[sphinx docs](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#ref-role) - Since MDX doesn't yet support this direct referencing, we have to rely on relative/root relative path resolution for [referencing other documents](https://docusaurus.io/docs/docs-markdown-features#referencing-other-documents). - - - -```rest -// highlight-next-line -:ref:`cloud_getting_started` - -where `cloud_getting_started` is id of the document given at top of RST file. - -Link label will by default be title of page. For custom link labels, the syntax might look like below. - -// highlight-next-line -:ref:`Remote schemas ` -``` - - - - ```markdown [Getting Started With Hasura Cloud](../relative/path/to/getting-started-document.mdx) [Remote Schemas](../relative/path/to/remote-schemas-document.mdx) ``` - - - ### Root Relative Links While relative paths works absolutely fine, this can easily lead to an absolute mess when files are moved around. Thus @@ -74,34 +35,18 @@ easier to find and replace. Find with old path and replace with new path. Find `/folder1/subfolder2/doc3.mdx` and replace with `/folder1/newsubfolder4/doc5.mdx` ``` -Since MDX doesn't yet support direct document referencing with `id/ref` unlike sphinx, we need to settle with root -relative path linking for now. The root relative link should start at `graphql` directory level. +The root relative link should start after the `latest` directory level. ``` -[MDX Root Relative Link](/rst-vs-mdx-guide/index.mdx#contents-covered) +[MDX Root Relative Actions Link](/actions/index.mdx) ``` -> [MDX Root Relative Link](/rst-vs-mdx-guide/index.mdx#contents-covered) - :::tip Don't forget the extension! Make sure to include file extension as MDX links are parsed as a file path and will be resolved correctly. ::: -:::info A quick note on id's in reStructuredText - -Similar to how a top level id will resolve to file/document, a sub-section can also have id's and they resolve to a -section within the document. - -This is similar to using hash in the url (`#sub-section`) to directly link to a section in the page. - -While the top level can just be a direct file path. The sub-section (h2's, h3's and stuff) can have id's with special -mdx syntax `{#id-for-sub-section}` - -![Referencing sub-section in rst vs markdown](/img/wiki/rst-vs-mdx-guide/link-sub-section-ids.png) - -::: :::danger be cautious with URL slug diff --git a/docs/wiki/rst-vs-mdx-guide/list-tables.mdx b/docs/wiki/docusaurus-mdx-guide/list-tables.mdx similarity index 80% rename from docs/wiki/rst-vs-mdx-guide/list-tables.mdx rename to docs/wiki/docusaurus-mdx-guide/list-tables.mdx index 70a5a783a41..898b32e62fa 100644 --- a/docs/wiki/rst-vs-mdx-guide/list-tables.mdx +++ b/docs/wiki/docusaurus-mdx-guide/list-tables.mdx @@ -11,32 +11,6 @@ import Link from '@docusaurus/Link'; Tables are the only complex stuff in markdown. -## Sphinx - RST - -```rest -.. list-table:: - :header-rows: 1 - :widths: 20 40 - - * - Field - - Description - - * - Region - - The region of the data centre where your New Relic account stores its data. `Read more about regions on New Relic docs. `_ - - * - API Key - - API keys are unique to your organization. An API key is required by the New Relic API to submit metrics and events to New Relic. You can get the API key from `here `__ if you are in New Relic US region and `here `__ if you're in New Relic EU region. - - * - Host - - The name of the originating host of the log and metrics. - - * - Custom Attributes - - Custom Attributes associated with your logs and metrics. A default source tag ``hasura-cloud-metrics`` is added to all exported logs and metrics. Attributes ``project_id`` and ``project_name`` are added to all exported metrics. - - * - Service Name - - The name of the application or service generating the log events. -``` - ## Docusaurus - MDX If the table consists of simple text and no complex UI and no column width control. This can be plain markdown syntax as below: @@ -88,7 +62,8 @@ Unfortunately, `markdown` doesn't have straightforward syntax to control the wid :::tip Few things to note: -If a table cell is mixed with text and markdown stuff (`code highlighters`, [links](/rst-vs-mdx-guide/links.mdx) etc., Please prefer `html` syntax over markdown as markdown won't be parsed correctly. +If a table cell is mixed with text and markdown elements (`code highlighters`, [links](/docusaurus-mdx-guide/links.mdx) +etc., Please prefer `html` syntax over markdown as markdown won't be parsed correctly. ```html @@ -197,53 +172,9 @@ Please do not that this is required only when there is a cell involving code blo -### Sphinx - RST -```rest {2-7} -.. list-table:: - :widths: 10 10 30 - :header-rows: 1 - * - Status code - - Description - - Response structure - - * - ``200`` - - Success - - .. parsed-literal:: - - Request specific - - * - ``400`` - - Bad request - - .. code-block:: haskell - - { - "path" : String, - "error" : String - } - - * - ``401`` - - Unauthorized - - .. code-block:: haskell - - { - "error" : String - } - - * - ``500`` - - Internal server error - - .. code-block:: haskell - - { - "error" : String - } -``` - -### Docusaurus - MDX - -The `:widths:` can be added as `width` attribute to `html` - `th`. And the `:header-rows:` determines the number of header rows to be considered for ``. - -Each row in RST syntax starts with `*` prefix (ex: `* - Status Code`). SO the first row will be header and rest of them will be `tr`s under table body. +The `:widths:` can be added as `width` attribute to `html` - `th`. And the `:header-rows:` determines the number of +header rows to be considered for ``. ```html {2-8} diff --git a/docs/wiki/docusaurus-mdx-guide/metadata.mdx b/docs/wiki/docusaurus-mdx-guide/metadata.mdx new file mode 100644 index 00000000000..78617d12f3c --- /dev/null +++ b/docs/wiki/docusaurus-mdx-guide/metadata.mdx @@ -0,0 +1,27 @@ +--- +sidebar_position: 3 +--- + +# Metadata & Frontmatter + +:::info + +Please refer to the Docusaurus [Markdown Frontmatter reference](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter) +for allowed properties in frontmatter. + +Please refer to [Metadata](https://docusaurus.io/docs/markdown-features/head-metadata) if it needs to be added as custom +meta outside frontmatter. + +::: + +```markdown + --- + title: Hasura GraphQL Engine Documentation + description: Hasura GraphQL Engine Documentation + keywords: + - hasura + - docs + - manual + - graphql engine + --- +``` \ No newline at end of file diff --git a/docs/wiki/docusaurus-mdx-guide/page-structure.mdx b/docs/wiki/docusaurus-mdx-guide/page-structure.mdx new file mode 100644 index 00000000000..d5a26e7cdd8 --- /dev/null +++ b/docs/wiki/docusaurus-mdx-guide/page-structure.mdx @@ -0,0 +1,103 @@ +--- +sidebar_label: Page Structure +sidebar_position: 0 +--- + +# 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 the root of the app - absolute import. So, doing +`@site/src/components/Thumbnail` is the 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 to the [Table of Contents](/docusaurus-mdx-guide/table-of-contents.mdx) section to understand more about +hwo to render this manually in between content and filtering items etc., + +## 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 ...: + +.... + + + +[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 +inconsistencies. \ No newline at end of file diff --git a/docs/wiki/rst-vs-mdx-guide/release-tag.mdx b/docs/wiki/docusaurus-mdx-guide/release-tag.mdx similarity index 58% rename from docs/wiki/rst-vs-mdx-guide/release-tag.mdx rename to docs/wiki/docusaurus-mdx-guide/release-tag.mdx index dc580193ffd..5bf88d770fe 100644 --- a/docs/wiki/rst-vs-mdx-guide/release-tag.mdx +++ b/docs/wiki/docusaurus-mdx-guide/release-tag.mdx @@ -5,26 +5,6 @@ import LatestRelease from "@site/src/components/LatestRelease"; # LatestRelease Tag - - - -```rest {3-5,9-11} -The current latest stable version is: - -.. raw:: html - - hasura/graphql-engine:latest - -The current latest pre-release version is: - -.. raw:: html - - hasura/graphql-engine:prerelease -``` - - - - ```jsx {1,5,9} import LatestRelease from "@site/src/components/LatestRelease"; @@ -37,8 +17,6 @@ The current latest pre-release version is: hasura/graphql-engine: ``` - - ## Result UI diff --git a/docs/wiki/rst-vs-mdx-guide/table-of-contents.mdx b/docs/wiki/docusaurus-mdx-guide/table-of-contents.mdx similarity index 66% rename from docs/wiki/rst-vs-mdx-guide/table-of-contents.mdx rename to docs/wiki/docusaurus-mdx-guide/table-of-contents.mdx index 16878bf2529..09d8316bf22 100644 --- a/docs/wiki/rst-vs-mdx-guide/table-of-contents.mdx +++ b/docs/wiki/docusaurus-mdx-guide/table-of-contents.mdx @@ -23,21 +23,6 @@ Below is auto listed TOC for this document This is the simplest way and is autogenerated on usage of `TOCInline` component from docusaurus. - - - -```rest -.. contents:: Table of contents - :backlinks: none - :depth: 2 - :local: -``` - -Please refer [reStructured text `content` Directives](https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents) for more insights into syntax and usage of `contents` directive. - - - - ```jsx import TOCInline from '@theme/TOCInline'; @@ -57,12 +42,11 @@ import { CustomTOCListHead } from "@site/src/components/CustomTOCList"; Will see more about this component in below sections. - - - :::info -- The `:depth:` param can be controlled by [`toc_min_heading_level` and `toc_max_heading_level`](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#toc_min_heading_level) meta for individual files and [`minHeadingLevel` and `maxHeadingLevel`](https://docusaurus.io/docs/api/themes/configuration#table-of-contents) for global theme config in docusaurus as given in docs. +- The `:depth:` param can be controlled by [`toc_min_heading_level` and `toc_max_heading_level`](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#toc_min_heading_level) +meta for individual files and [`minHeadingLevel` and `maxHeadingLevel`](https://docusaurus.io/docs/api/themes/configuration#table-of-contents) +for global theme config in docusaurus as given in docs. - The `:backlinks:` seems to be set to `none` for all and also there is no direct replacement in MDX via Docusaurus. So, can be ignored. - The `:local` can be ignored as well cause the `TOCInline` component works only for local (same) document @@ -70,7 +54,8 @@ Will see more about this component in below sections. :::caution Important Note -Please ignore top level TOC (the one at beginning of file). Only add for sub-section TOCs. This is to avoid redundancy as TOC is available on right sidebar. +Please ignore top-level TOC (the one at beginning of the file). Only add for sub-section TOCs. This is to avoid +redundancy as TOC is available on right sidebar. ::: @@ -78,8 +63,8 @@ Please ignore top level TOC (the one at beginning of file). Only add for sub-sec If one individual section requires to have its own TOC. Below is how it can be achieved in docusaurus. -So, a bit of good and bad news :(. -Unlike Sphinx, changing `depth` (`minHeadingLevel` or `maxHeadingLevel`) value for auto generated TOC will not auto generate a sub table of content for that particular section. +Changing the `depth` (`minHeadingLevel` or `maxHeadingLevel`) value for auto-generated TOC will not auto-generate a sub +table of contents for that particular section. ```rest {3} .. contents:: Table of contents @@ -96,7 +81,7 @@ To only list a sub-section list from below Table of Contents, -For this section, the url is `/docs/wiki/rst-vs-mdx-guide/table-of-contents/#partial-sub-table-of-contents`, hence: +For this section, the url is `/docs/wiki/docusaurus-mdx-guide/table-of-contents/#partial-sub-table-of-contents`, hence: ```jsx {4} // Render only the "Partial (Sub) Table of Contents" sub-items if any. @@ -144,28 +129,10 @@ Custom/Manually generated TOC can be a simple list or a group of lists (like a r ### Simple List - - - -```rest - .. toctree:: - :maxdepth: 1 - :titlesonly: - - allow-lists - api-limits - disable-graphql-introspection - rotating-admin-secrets -``` - -Please refer [reStructured text `toctree` Directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents) for more insights into syntax and usage of `toctree` directive. - - - - Unfortunately, there is no direct alternative for this in either MDX or Docusaurus. -So, have to rely on simple MDX links and manually find file paths, similar to how we handle refs in [Links](/rst-vs-mdx-guide/links.mdx#internal-links). +So, we have to rely on simple MDX links and manually find file paths, similar to how we handle refs in +[Links](/docusaurus-mdx-guide/links.mdx#internal-links). ```markdown - [Allow Lists](/graphql/cloud/security/allow-lists.mdx) @@ -198,16 +165,15 @@ import { If you notice, we have added extension to the paths in link where as in `` component we didn't. -That's because, the MDX links are treated as file-paths and is resolved to generated url paths automatically by docusaurus. -On the other hand, the path in `Link` component should already be a url path as it cannot resolve file-paths. +That's because, the MDX links are treated as file-paths and is resolved to generated url paths automatically by +docusaurus. On the other hand, the path in `Link` component should already be a url path as it cannot resolve +file-paths. -Best practice is to keep the directory/file path structure and url structure same to avoid the maintenance burden when using both types of syntax. +The best practice is to keep the directory/file path structure and url structure same to avoid the maintenance burden +when using both types of syntax. ::: - - - #### Result UI will render something like below. @@ -215,42 +181,8 @@ will render something like below. ### Group of Lists Its a list of simple lists (UI wise). - - - -```rest - .. container:: toc-list - - .. container:: toc-list-section - - .. container:: toc-list-head - - API Security - - .. container:: toc-list-content - - - :ref:`api_limits` - - :ref:`allow_lists` - - .. container:: toc-list-section - - .. container:: toc-list-head - - Reference - - .. container:: toc-list-content - - - :ref:`cloud_api_reference` - - :ref:`glossary` - - :ref:`hasurapro_cli` -``` - -Please refer [reStructured text `toctree` Directive](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents) for more insights into syntax and usage of `toctree` directive. - - - - -Unfortunately, there is no direct alternative for this in either MDX or Docusaurus. So, have to list these links manually using this `CustomTOCList` component. +Unfortunately, there is no direct alternative for this in either MDX or Docusaurus. So we have to list these links +manually using this `CustomTOCList` component. ```jsx import Link from '@docusaurus/Link'; @@ -286,12 +218,9 @@ Unfortunately, there is no direct alternative for this in either MDX or Docusaur ``` - - - #### Result UI -will render something like below. Please note that links will be broken as they are just samples. +This will render something like the below. Please note that links will be broken as they are just samples. @@ -315,14 +244,14 @@ will render something like below. Please note that links will be broken as they :::tip How to use links within React? -- Please refer [Links in React](/rst-vs-mdx-guide/links.mdx#links-in-react) section in Links. +- Please refer to the [Links in React](/docusaurus-mdx-guide/links.mdx#links-in-react) section in Links. ```jsx import Link from '@docusaurus/Link'; -Root Relative Links +Root Relative Links ``` -- Please refer the [Root Relative Links](/wiki/rst-vs-mdx-guide/links#root-relative-links) section too. +- Please refer to the [Root Relative Links](/wiki/docusaurus-mdx-guide/links#root-relative-links) section too. ::: diff --git a/docs/wiki/rst-vs-mdx-guide/tabs.mdx b/docs/wiki/docusaurus-mdx-guide/tabs.mdx similarity index 75% rename from docs/wiki/rst-vs-mdx-guide/tabs.mdx rename to docs/wiki/docusaurus-mdx-guide/tabs.mdx index 31324e93504..a9ccd47e23a 100644 --- a/docs/wiki/rst-vs-mdx-guide/tabs.mdx +++ b/docs/wiki/docusaurus-mdx-guide/tabs.mdx @@ -9,28 +9,6 @@ import TabItem from '@theme/TabItem'; Should be a straightforward syntax replacement: - - - -```rest -.. rst-class:: api_tabs -// highlight-next-line -.. tabs:: - - // highlight-next-line - .. tab:: Console - - Click the ``Reload`` button in the ``Remote schema`` section on the Hasura console. - - // highlight-next-line - .. tab:: API - - Make a request to the :ref:`reload_remote_schema` API. -``` - - - - ```jsx import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -49,9 +27,6 @@ Make a request to the [reload_remote_schema](#) API. ``` - - - Which should render like below: diff --git a/docs/wiki/rst-vs-mdx-guide/thumbnail.mdx b/docs/wiki/docusaurus-mdx-guide/thumbnail.mdx similarity index 63% rename from docs/wiki/rst-vs-mdx-guide/thumbnail.mdx rename to docs/wiki/docusaurus-mdx-guide/thumbnail.mdx index 04883faa607..6c161fcaca1 100644 --- a/docs/wiki/rst-vs-mdx-guide/thumbnail.mdx +++ b/docs/wiki/docusaurus-mdx-guide/thumbnail.mdx @@ -8,30 +8,12 @@ import Thumbnail from '@site/src/components/Thumbnail'; # Thumbnail -MDX doesn't have straight forward alternative for `thumbnail` custom directive from Sphinx. So, created a new component -`Thumbnail` to function as alternative. - - - - -```rest -.. thumbnail:: /img/account-management/billing/add_new_card.png - :alt: add a new card - :width: 437px -``` - - - - ```jsx import Thumbnail from '@site/src/components/Thumbnail'; ; ``` - - - Just pass in all the valid attributes for image as props. ## Result UI diff --git a/docs/wiki/index.mdx b/docs/wiki/index.mdx index 40b759f472b..cf479da4626 100644 --- a/docs/wiki/index.mdx +++ b/docs/wiki/index.mdx @@ -1,10 +1,8 @@ --- -sidebar_label: Index +sidebar_label: Introduction sidebar_position: 10 --- -import Thumbnail from '@site/src/components/Thumbnail'; - # Hasura Docs Wiki Welcome to the Hasura Docs Wiki! We're glad you're here and are excited to see your docs contributions. They're going to @@ -89,7 +87,3 @@ tools over time to determine its quality and impact for our user audience. ## Next steps... After your local environment is set up, feel free to poke around the style guide, explanation of our page structures, and info on working with Docusaurus (our docs framework). - -- [Contributing to Docs](/contributions.mdx) -- [Page Structure](/page-structure.mdx) -- [Working With Docusaurus](/working-with-docusaurus.mdx) diff --git a/docs/wiki/page-structure.mdx b/docs/wiki/page-structure.mdx deleted file mode 100644 index d4ad94bfccb..00000000000 --- a/docs/wiki/page-structure.mdx +++ /dev/null @@ -1,309 +0,0 @@ ---- -sidebar_label: Page Structure -sidebar_position: 30 ---- - -# 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'; - -; -``` - -- 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'; - -; -``` - -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 ...: - -.... - - - -[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. diff --git a/docs/wiki/rst-vs-mdx-guide/_category_.json b/docs/wiki/rst-vs-mdx-guide/_category_.json deleted file mode 100644 index 72b2b274c22..00000000000 --- a/docs/wiki/rst-vs-mdx-guide/_category_.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "label": "RST vs MDX Guide", - "position": 60, - "link": { - "type": "generated-index", - "title": "reStructuredText vs Markdown Guide Index" - } -} diff --git a/docs/wiki/rst-vs-mdx-guide/index.mdx b/docs/wiki/rst-vs-mdx-guide/index.mdx deleted file mode 100644 index be5e3a278b0..00000000000 --- a/docs/wiki/rst-vs-mdx-guide/index.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -description: A brief intro to RST vs MDX Guide format -sidebar_label: Get Started -sidebar_position: 1 ---- - -# reStructured Text vs Markdown Guide - -Since we moved our docs from `reStructured` to `markdown`. This page will act as a reference guide for the syntactical -differences of `rst` and `mdx` for authors who are comfortable with rst. - -This page will cover all the factors that require to comfortably write a doc page. If missed any, please let us know. - -Please read about the [doc page structure here](/page-structure.mdx). - -## Guide Format - -### Tabs - -Most of this guide will include tabs for syntactical examples wherever applicable. - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - -Snippets in `RST` syntax will be shown in this tab. - - - - -Snippets in `MDX` syntax will be shown in this tab. - - - - -
- -### Normal Headings - -Wherever Tab system is quite difficult to understand/implement. The `Sphinx - RST` and `Docusaurus - MDX` will just be -normal sections with headings in respective order. - -#### Sphinx - RST - -Snippets in `RST` syntax will be shown in this tab. - -#### Docusaurus - MDX - -Snippets in `MDX` syntax will be shown in this tab. - -
- -### Admonitions - -:::info - -Admonitions are used wherever applicable to provide reference / helpful links and info. - -::: - -
- -## Contents Covered - -Below are primary topics/syntaxes/extensions that are covered in this guide. - -- [Headings & Ids](/rst-vs-mdx-guide/headings.mdx) -- [Metadata + Frontmatter](/rst-vs-mdx-guide/metadata.mdx) -- [Table of Contents](/rst-vs-mdx-guide/table-of-contents.mdx) -- [Links](/rst-vs-mdx-guide/links.mdx) -- [Thumbnail](/rst-vs-mdx-guide/thumbnail.mdx) -- [Notes / Admonitions](/rst-vs-mdx-guide/admonitions.mdx) -- [Code Blocks with Line Highlighting](/rst-vs-mdx-guide/code-blocks.mdx) -- [GraphiQL IDE](/rst-vs-mdx-guide/graphiql-ide.mdx) -- [Tabs](/rst-vs-mdx-guide/tabs.mdx) -- [List Tables](/rst-vs-mdx-guide/list-tables.mdx) diff --git a/docs/wiki/rst-vs-mdx-guide/metadata.mdx b/docs/wiki/rst-vs-mdx-guide/metadata.mdx deleted file mode 100644 index ab9d158d34b..00000000000 --- a/docs/wiki/rst-vs-mdx-guide/metadata.mdx +++ /dev/null @@ -1,45 +0,0 @@ ---- -sidebar_position: 3 ---- - -# Metadata & Frontmatter - -:::info - -Please refer [Markdown Frontmatter](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter) for allowed properties in frontmatter. - -Please refer [Metadata](https://docusaurus.io/docs/markdown-features/head-metadata) if it needs to be added as custom meta outside frontmatter. - -::: - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - - - - -```rest - .. meta:: - :description: Hasura GraphQL engine documentation - :keywords: hasura, docs, manual, graphql engine - - .. title:: Hasura GraphQL Engine Documentation -``` - - - - -```markdown - --- - title: Hasura GraphQL Engine Documentation - description: Hasura GraphQL Engine Documentation - keywords: - - hasura - - docs - - manual - - graphql engine - --- -``` - - - diff --git a/docs/wiki/style/_category_.json b/docs/wiki/style/_category_.json index 4d6729849d0..3923da88788 100644 --- a/docs/wiki/style/_category_.json +++ b/docs/wiki/style/_category_.json @@ -1,4 +1,8 @@ { "label": "Style", - "position": 40 + "position": 50, + "link": { + "type": "generated-index", + "title": "Documentation Style Guide Index" + } } diff --git a/docs/wiki/style/general.mdx b/docs/wiki/style/general.mdx index b706e5b2113..b37d617d517 100644 --- a/docs/wiki/style/general.mdx +++ b/docs/wiki/style/general.mdx @@ -18,3 +18,13 @@ slug: general - All lines in markdown should break at **120 characters** for better readability in IDEs. 120 is useful because it still allows side-by-side editing on most screens and closely matches the line length of the final output page at max width. +- Add appropriate cross-links in content to assist users. + - If you refer to some functionality that is documented in some other docs page, add a link to that page. + - 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. + diff --git a/docs/wiki/style/headings.mdx b/docs/wiki/style/headings.mdx index 269ba35cfab..6323b2d38f7 100644 --- a/docs/wiki/style/headings.mdx +++ b/docs/wiki/style/headings.mdx @@ -13,4 +13,10 @@ slug: headings * Headings should use `Title Capitalization Like This`. * Subheadings, anything less than `h1` or markdown level 1: `#`, should use `Sentence capitalization like this`. * Headings should not end with a period. -* Leave a blank line above and below headings. \ No newline at end of file +* Leave a blank line above and below headings. +* Add an introduction section as `## Introduction` with a short overview of what the page is about. +* 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. \ No newline at end of file diff --git a/docs/wiki/style/images.mdx b/docs/wiki/style/images.mdx index 89486d06a3c..74886f96cdd 100644 --- a/docs/wiki/style/images.mdx +++ b/docs/wiki/style/images.mdx @@ -49,7 +49,7 @@ user. - Use hex color 
#FC336D
for all image markup. - Use rounded corners on callout blocks. -- Arrows should be placed at 90° angles, not at arbitrary angles. +- Generally, if you want to show selecting something, use borders. If you want to show clicking on a button, use arrows. - Don't make arrows unnecessarily long or short. - Use step numbering of a number in a circle. Start count from 1, not array 0 notation. - Use the [Skitch markup app](https://evernote.com/products/skitch) if possible. diff --git a/docs/wiki/style/index.mdx b/docs/wiki/style/index.mdx deleted file mode 100644 index ae5b42ee268..00000000000 --- a/docs/wiki/style/index.mdx +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Style -description: Style guide for Hasura documentation -keywords: - - hasura - - style - - images - - code blocks - - markdown -slug: index ---- - -# Hasura Documentation Style Guide - -To maintain a consistent appearance, we utilize a style guide for authoring documentation pages. For quick reference, -you'll find the most common style topics below: - -- [General](/general.mdx) -- [Bullet Lists](/bullets.mdx) -- [Code Blocks](/code-blocks.mdx) -- [Headings](/headings.mdx) -- [Images](/images.mdx) -- [Semantics](/semantics.mdx) -- [Tables](/tables.mdx) diff --git a/docs/wiki/style/links.mdx b/docs/wiki/style/links.mdx new file mode 100644 index 00000000000..7787f4b8632 --- /dev/null +++ b/docs/wiki/style/links.mdx @@ -0,0 +1,44 @@ +--- +title: Links +description: Style for links in documentation +keywords: + - hasura + - style + - links +--- + +# 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](/docusaurus-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/) + + +:::info 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`. + +::: diff --git a/docs/wiki/working-with-docusaurus.mdx b/docs/wiki/working-with-docusaurus.mdx index c34a85f5601..8eafaba971c 100644 --- a/docs/wiki/working-with-docusaurus.mdx +++ b/docs/wiki/working-with-docusaurus.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 50 +sidebar_position: 60 --- # Working with Docusaurus