Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity
zulip/help/code-blocks.md

123 lines
4.3 KiB
Markdown
Raw Normal View History

help: Update Message formatting section and page on code blocks.
2023-03-10 06:18:50 +01:00
# Code blocks
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
help: Update Message formatting section and page on code blocks.
2023-03-10 06:18:50 +01:00
{!code-blocks-intro.md!}
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
help: Update Message formatting section and page on code blocks.
2023-03-10 06:18:50 +01:00
## Examples
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
help: Update Message formatting section and page on code blocks.
2023-03-10 06:18:50 +01:00
{!code-blocks-examples.md!}
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
## Language tagging
Tagging a code block with a language enables syntax highlighting and
help: Update Message formatting section and page on code blocks.
2023-03-10 06:18:50 +01:00
(if configured) [code playgrounds](#code-playgrounds). Zulip supports syntax
highlighting for hundreds of languages.
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
A code block can be tagged by typing the language name after the fence
(` ``` `) that begins a code block, as shown here. Typeahead will
help you enter the name for the language. The **Short names** values
from the [Pygments lexer documentation][pygments-lexers] are the
complete set of values that support syntax highlighting.
~~~
``` python
print("Hello world!")
```
~~~
### Default code block language
Organization administrators can also configure a default language for code
blocks, which will be used whenever the code block has no tag.
{!admin-only.md!}
{start_tabs}
{settings_tab|organization-settings}
1. Under **Other settings**, edit **Default language for code blocks**.
{end_tabs}
When a default language is configured, one can use ````text` to display code
blocks without any syntax highlighting (E.g. to paste an error message).
## Code playgrounds
Code playgrounds are interactive in-browser development environments, such as
[replit](https://replit.com), that are designed to make it convenient to edit
and debug code. Code playgrounds can be configured for any programming language.
Zulip code blocks that are tagged with the language will have a button visible
on hover that allows you to open the code block in the code playground site.
### Add a custom code playground
{!admin-only.md!}
{start_tabs}
{settings_tab|playground-settings}
1. Under **Add a new code playground**, enter a **Name**, **Language** and **URL
prefix**.
1. Click **Add code playground**.
{end_tabs}
For example, to configure code playgrounds for languages like Python or
realm_playgrounds: Replace url_prefix with url_template. Dropping support for url_prefix for RealmPlayground, the server now uses url_template instead only for playground creation, retrieval and audit logging upon removal. This does the necessary handling so that url_template is expanded with the extracted code. Fixes #25723. Signed-off-by: Zixuan James Li <p359101898@gmail.com>
2023-05-27 05:04:50 +02:00
JavaScript, you could specify the language and URL templates as:
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
realm_playgrounds: Replace url_prefix with url_template. Dropping support for url_prefix for RealmPlayground, the server now uses url_template instead only for playground creation, retrieval and audit logging upon removal. This does the necessary handling so that url_template is expanded with the extracted code. Fixes #25723. Signed-off-by: Zixuan James Li <p359101898@gmail.com>
2023-05-27 05:04:50 +02:00
* `Python` and `https://replit.com/languages/python3/code={code}`
* `JavaScript` and `https://replit.com/languages/javascript/code={code}`
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
When a code block is labeled as Python or JavaScript (either explicitly or by
organization default), users would get a on-hover option to open the code block
Fix typos using codespell. The command: codespell --skip='./locale,*.svg,./docs/translating,postgresql.conf.template.erb,.*fixtures,./yarn.lock,./docs/THIRDPARTY,./tools/setup/emoji/emoji_names.py,./tools/setup/emoji/emoji_map.json,./zerver/management/data/unified_reactions.json' --ignore-words=codespell_ignore_words.txt . The content of codespell_ignore_words: ``` te ans pullrequest ist cros wit nwe circularly ned ba ressemble ser sur hel fpr alls nd ot ```
2021-05-18 14:44:05 +02:00
in the specified code playground.
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
realm_playgrounds: Replace url_prefix with url_template. Dropping support for url_prefix for RealmPlayground, the server now uses url_template instead only for playground creation, retrieval and audit logging upon removal. This does the necessary handling so that url_template is expanded with the extracted code. Fixes #25723. Signed-off-by: Zixuan James Li <p359101898@gmail.com>
2023-05-27 05:04:50 +02:00
!!! tip ""
Code playgrounds use [RFC 6570](https://www.rfc-editor.org/rfc/rfc6570.html)
compliant URL templates to describe how links should be generated. Zulip's
rendering engine will pass the URL-encoded code from the code block as the
`code` parameter, denoted as `{code}` in this URL template, in order to
generate the URL. You can refer to parts of the documentation on URL
templates from [adding a custom linkifier](/help/add-a-custom-linkifier).
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
### Technical details
* You can configure multiple playgrounds for a given language; if you do that,
the user will get to choose which playground to open the code in.
docs: Fix capitalization mistakes. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2021-05-10 07:02:14 +02:00
* The **Language** field is the human-readable Pygments language name for that
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
programming language. The language tag for a code block is internally mapped
docs: Fix many spelling mistakes. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-08 00:13:33 +01:00
to these human-readable Pygments names; e.g., `py3` and `py` are mapped to
help: Remove typeahead workaround mentioned in our code-blocks doc. In 215320bc721038001b506975dab0035157427a2e, we added the typeahead for the `pygments_name` field which helped lookup the human-readable `pretty_name`. However, we forgot to remove the workaround method mentioned in the docs to lookup the name before the typeahead was introduced.
2021-05-08 13:04:29 +02:00
`Python`. One can use the typeahead (which appears when you type something
docs: Add missing space to compound verbs “back up”, “log in”, etc. Noun: backup, login, logout, lookup, setup. Verb: back up, log in, log out, look up, set up. Signed-off-by: Anders Kaseorg <anders@zulip.com>
2022-02-07 20:41:10 +01:00
or just click on the language field) to look up the Pygments name.
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
realm_playgrounds: Replace url_prefix with url_template. Dropping support for url_prefix for RealmPlayground, the server now uses url_template instead only for playground creation, retrieval and audit logging upon removal. This does the necessary handling so that url_template is expanded with the extracted code. Fixes #25723. Signed-off-by: Zixuan James Li <p359101898@gmail.com>
2023-05-27 05:04:50 +02:00
* The links for opening code playgrounds are always constructed by substituting
the URL-encoded contents of the code block into `code` variable in the URL template.
The URL template is required to contain exactly one variable named `code`.
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
* Code playground sites do not always clearly document their URL format; often
you can just get the prefix from your browser's URL bar.
* You can also use a custom language name to implement simple integrations.
For example, a code block tagged with the "language" `send_tweet` could be
used with a "playground" that sends the content of the code block as a Tweet.
help: Update Message formatting section and page on code blocks.
2023-03-10 06:18:50 +01:00
If you have any trouble setting up a code playground, please [contact
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
us](/help/contact-support) with details on what you're trying to do, and we'll
be happy to help you out.
## Related articles
help: Update Message formatting section and page on code blocks.
2023-03-10 06:18:50 +01:00
* [Message formatting](/help/format-your-message-using-markdown)
* [LaTeX](/help/latex)
* [Spoilers](/help/spoilers)
* [Quote and reply](/help/quote-and-reply)
user docs: Create separate "Code blocks" user documentation page. * Move the extended documentation of code blocks to a separate page. * Merge "code playgrounds" documentation to be a section of that page. * Document copy widget on code blocks. * This commit changes how we refer to "```python" type syntax for code blocks. Instead of being called a syntax highlighting label, this is now referred to as a "language tag", since it serves both syntax highlighting and playgrounds. * Remap all the links. * Advertise this new page in various places that previously did not have a link.
2021-05-05 02:05:47 +02:00
[pygments-lexers]: https://pygments.org/docs/lexers/
[get_lexer_by_name]: https://pygments-doc.readthedocs.io/en/latest/lexers/lexers.html#pygments.lexers.get_lexer_by_name