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

185 lines
5.8 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: Document new formatting buttons. Updates icons and adds instructions for formatting text using the new formatting buttons in the compose box. Fixes #27850.
2023-12-01 06:33:04 +01:00
## Insert code formatting
help: Explain smart formatting buttons in more detail.
2023-12-05 09:05:43 +01:00
Zulip's compose box has a smart **Code** (<i class="zulip-icon
zulip-icon-code"></i>) button, which inserts contextually appropriate code
formatting:
- If no text is selected, the button inserts code block (` ``` `) formatting.
- If selected text is on one line, the button inserts code span (`` ` ``)
formatting.
- If selected text is on multiple lines, the button inserts code block (` ``` `)
formatting.
help: Document new formatting buttons. Updates icons and adds instructions for formatting text using the new formatting buttons in the compose box. Fixes #27850.
2023-12-01 06:33:04 +01:00
{start_tabs}
{tab|via-compose-box-buttons}
{!start-composing.md!}
1. _(optional)_ Select the text you want to format.
1. Click the **Code** (<i class="zulip-icon zulip-icon-code"></i>) icon at the
help: Explain smart formatting buttons in more detail.
2023-12-05 09:05:43 +01:00
bottom of the compose box to insert code formatting.
1. _(optional)_ To enable syntax highlighting in a code bock, start typing the
name of the desired programming language directly after the initial ` ``` `.
Select the language from the auto-complete suggestions.
help: Document new formatting buttons. Updates icons and adds instructions for formatting text using the new formatting buttons in the compose box. Fixes #27850.
2023-12-01 06:33:04 +01:00
!!! tip ""
You can also use the **Code** (<i class="zulip-icon zulip-icon-code"></i>)
icon to remove existing code formatting from the selected text.
{tab|via-markdown}
{!start-composing.md!}
1. To create an inline code span, use single backticks around the text:
~~~
`text`
~~~
To create a code block, use triple backticks around the text:
~~~
```
def f(x):
return x+1
```
~~~
To enable syntax highlighting, use triple backticks followed by one or more
letters, and select the desired programming language from the auto-complete
suggestions.
~~~
```python
def fib(n):
# TODO: base case
return fib(n-1) + fib(n-2)
```
~~~
!!! tip ""
You can also use `~~~` to start code blocks, or just indent the code 4 or more
spaces.
{end_tabs}
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
playgrounds: Replace replit playground example with Rust playground. Passing code to replit as a URL parameter no longer works.
2024-02-23 08:19:28 +01:00
Code playgrounds are interactive in-browser development environments
that are designed to make it convenient to edit
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
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}
playgrounds: Replace replit playground example with Rust playground. Passing code to replit as a URL parameter no longer works.
2024-02-23 08:19:28 +01:00
1. Under **Add a new code playground**, enter a **Language**, **Name**, and
**URL template**.
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
1. Click **Add code playground**.
{end_tabs}
playgrounds: Replace replit playground example with Rust playground. Passing code to replit as a URL parameter no longer works.
2024-02-23 08:19:28 +01:00
For example, to configure code a playground for Rust, you could specify the
language and URL template as `Rust` and `https://play.rust-lang.org/?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
playgrounds: Replace replit playground example with Rust playground. Passing code to replit as a URL parameter no longer works.
2024-02-23 08:19:28 +01:00
When a code block is labeled as `rust` (either explicitly or by organization
default), users would get an on-hover option to open the code block 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