mirror of
https://github.com/hasura/graphql-engine.git
synced 2024-12-15 09:22:43 +03:00
7a552d34da
**WIP** ## Description ✍️ Adding a style section to the documentation wiki. This is a distillation and continuation of the notes started by @marionschleifer and @rikinsk at https://docs.google.com/document/d/1lD7IVEjtv5Sf9BaVqzefLywG-kNpuM40I84ThIUSmwg/edit * _Everything is very much in a WIP stage._ * Everything is on one page for now, but if it warrants it, each sections could be broken out into separate parts under a main `style` section. @robertjdominguez Please let me know your thoughts too. **Anyone** please feel free to edit and push to this branch. - Sean PR-URL: https://github.com/hasura/graphql-engine-mono/pull/4642 Co-authored-by: parklifeio <33491775+parklifeio@users.noreply.github.com> Co-authored-by: Rob Dominguez <24390149+robertjdominguez@users.noreply.github.com> GitOrigin-RevId: 48a26500114efcef22278d4e673ce0289bd7d7db
55 lines
1.9 KiB
Plaintext
55 lines
1.9 KiB
Plaintext
---
|
|
title: Code Blocks
|
|
description: Style for code blocks in documentation
|
|
keywords:
|
|
- hasura
|
|
- style
|
|
- code blocks
|
|
slug: code-blocks
|
|
---
|
|
|
|
# Code Blocks
|
|
|
|
* All code blocks should be indented 2 spaces by default.
|
|
* Order fields for greater understanding.
|
|
* Remove parts of code if necessary in order to provide the greatest clarity to the user.
|
|
* Use only mandatory fields to keep examples concise.
|
|
* Use MDX [code block highlighting](https://docusaurus.io/docs/markdown-features/code-blocks#line-highlighting) to
|
|
draw the user's attention to which lines the user should focus on.
|
|
* Show incorrect methods and common errors to improve the user's understanding but make sure they are very well
|
|
highlighted as incorrect.
|
|
* Use single quotes instead of double quotes except where necessary eg: JSON
|
|
* Arrays in code should be split onto multiple lines, unless there is only one member of the array.
|
|
* When specifying code for the Hasura API, you can use either `curl` or an `http` block depending on whichever is
|
|
clearer for the user.
|
|
|
|
### HTTP
|
|
|
|
* All HTTP headers must begin with `First-Letter-Capitalized-Like-This`.
|
|
* HTTP blocks should run without changes if they are pasted into Postman, for example.
|
|
|
|
### Javascript
|
|
|
|
* Use semicolons `;` at the end of statements.
|
|
* Use single quotes instead of double quotes.
|
|
|
|
### JSON
|
|
|
|
* Indent 2 spaces.
|
|
* Do not include comments in JSON
|
|
|
|
### Shell
|
|
|
|
* Specify `bash` as code type for shell commands.
|
|
* Try to break separate commands into separate code blocks or else chain commands with `&&` or break into multi-line
|
|
with `\`.
|
|
* Shell commands can include comments _before_ the command prefixed with `#`.
|
|
* If you would like to include output of the command, add it in a new block with `text` type.
|
|
|
|
### YAML
|
|
|
|
* YAML should always be indented by 2 spaces as per the spec.
|
|
* Include only the relevant part of the code if it provides more clarity to the user. Indicate ommitted lines with
|
|
`...`
|
|
|