mirror of
https://github.com/zulip/zulip.git
synced 2025-11-01 04:23:46 +00:00
docs: Capitalize Markdown consistently.
Signed-off-by: Anders Kaseorg <anders@zulip.com>
This commit is contained in:
committed by
Tim Abbott
parent
60a25b2721
commit
768f9f93cd
@@ -30,7 +30,7 @@ Our API documentation is defined by a few sets of files:
|
||||
[OpenAPI configuration](../documentation/openapi.md) at
|
||||
`zerver/openapi/zulip.yaml`.
|
||||
* The top-level templates live under `templates/zerver/api/*`, and are
|
||||
written using the markdown framework that powers our [user
|
||||
written using the Markdown framework that powers our [user
|
||||
docs](../documentation/user.md), with some special extensions for
|
||||
rendering nice code blocks and example responses. We expect to
|
||||
eventually remove most of these files where it is possible to
|
||||
@@ -268,16 +268,16 @@ above.
|
||||
comments. The lines inside these comments are what will be displayed as the
|
||||
code example on our `/api` page.
|
||||
|
||||
1. Finally, write the markdown file for your API endpoint under
|
||||
1. Finally, write the Markdown file for your API endpoint under
|
||||
`templates/zerver/api/`. This is usually pretty easy to template
|
||||
off existing endpoints; but refer to the system explanations above
|
||||
for details.
|
||||
|
||||
1. Add the markdown file to the index in `templates/zerver/help/include/rest-endpoints.md`.
|
||||
1. Add the Markdown file to the index in `templates/zerver/help/include/rest-endpoints.md`.
|
||||
|
||||
1. Test your endpoint, pretending to be a new user in a hurry, by
|
||||
visiting it via the links on `http://localhost:9991/api` (the API
|
||||
docs are rendered from the markdown source files on page load, so
|
||||
docs are rendered from the Markdown source files on page load, so
|
||||
just reload to see an updated version as you edit). You should
|
||||
make sure that copy-pasting the code in your examples works, and
|
||||
post an example of the output in the pull request.
|
||||
@@ -287,7 +287,7 @@ above.
|
||||
## Why a custom system?
|
||||
|
||||
Given that our documentation is written in large part using the
|
||||
OpenAPI format, why maintain a custom markdown system for displaying
|
||||
OpenAPI format, why maintain a custom Markdown system for displaying
|
||||
it? There's several major benefits to this system:
|
||||
|
||||
* It is extremely common for API documentation to become out of date
|
||||
|
||||
@@ -39,7 +39,7 @@ form `/help/foo`; with special cases for `/help/` going to `index.md` and
|
||||
are usually linked from `static/images/help/`.
|
||||
|
||||
This means that you can contribute to the Zulip user documentation by just
|
||||
adding to or editing the collection of markdown files under
|
||||
adding to or editing the collection of Markdown files under
|
||||
`templates/zerver/help`. If you have the Zulip development environment
|
||||
setup, you simply need to reload your browser on
|
||||
`http://localhost:9991/help/foo` to see the latest version of `foo.md`
|
||||
@@ -100,7 +100,7 @@ your documentation to help improve its readability:
|
||||
|
||||
* Since raw HTML is supported in Markdown, you can include arbitrary
|
||||
HTML/CSS in your documentation as needed.
|
||||
* Code blocks allow you to highlight syntax, similar to Zulip's own markdown.
|
||||
* Code blocks allow you to highlight syntax, similar to Zulip's own Markdown.
|
||||
* Anchor tags can be used to link to headers in other documents.
|
||||
* [Images](#images) of Zulip UI can be added to documentation.
|
||||
* Inline [icons](#icons) used to refer to features in the Zulip UI.
|
||||
@@ -108,7 +108,7 @@ HTML/CSS in your documentation as needed.
|
||||
documentation.
|
||||
* You can create special highlight warning blocks using
|
||||
[tips and warnings](#tips-and-warnings).
|
||||
* You can create tabs using [markdown tab switcher](#tab-switcher).
|
||||
* You can create tabs using [Markdown tab switcher](#tab-switcher).
|
||||
|
||||
### Images
|
||||
|
||||
@@ -232,7 +232,7 @@ should be formatted as a continuation of a numbered step.
|
||||
|
||||
### Tab Switcher
|
||||
|
||||
Our markdown processor supports easily creating a tab switcher widget
|
||||
Our Markdown processor supports easily creating a tab switcher widget
|
||||
design to easily show the instructions for different
|
||||
[platforms](https://zulip.com/help/logging-out) in user docs,
|
||||
languages in API docs, etc. To create a tab switcher, write:
|
||||
|
||||
Reference in New Issue
Block a user