mirror of
https://github.com/zulip/zulip.git
synced 2025-11-03 21:43:21 +00:00
dedea23745
These files are not Jinja2 templates, so there's no reason that they needed to be inside `templates/zerver`. Moving them to the top level reflects their importance and also makes it feel nicer to work on editing the help center content, without it being unnecessary buried deep in the codebase.
140 lines
4.5 KiB
Markdown
140 lines
4.5 KiB
Markdown
# Code spans and blocks
|
|
|
|
Zulip supports the standard [Markdown syntax][markdown] for inline
|
|
code spans and code blocks:
|
|
|
|
~~~
|
|
Inline code span: `let x = 5`
|
|
|
|
Code block:
|
|
```
|
|
def f(x):
|
|
return x+1
|
|
```
|
|
|
|
Syntax highlighting:
|
|
```python
|
|
def fib(n):
|
|
# TODO: base case
|
|
return fib(n-1) + fib(n-2)
|
|
```
|
|
~~~
|
|
|
|
Sending the above message in Zulip will render like this:
|
|
|
|
|
|
|
|
You can also use `~~~` to start code blocks, or just indent the code 4 or more
|
|
spaces.
|
|
|
|
A widget in the top right corner of code blocks allows you to easily
|
|
copy the code to your clipboard.
|
|
|
|
## Language tagging
|
|
|
|
Tagging a code block with a language enables syntax highlighting and
|
|
(if configured) [code playgrounds](#code-playgrounds). Zulip supports syntax highlighting
|
|
for hundreds of languages.
|
|
|
|
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
|
|
JavaScript, you could specify the language and URL prefix fields as:
|
|
|
|
* `Python` and `https://replit.com/languages/python3/?code=`
|
|
* `JavaScript` and `https://replit.com/languages/javascript/?code=`
|
|
|
|
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
|
|
in the specified code playground.
|
|
|
|
### 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.
|
|
|
|
* The **Language** field is the human-readable Pygments language name for that
|
|
programming language. The language tag for a code block is internally mapped
|
|
to these human-readable Pygments names; e.g., `py3` and `py` are mapped to
|
|
`Python`. One can use the typeahead (which appears when you type something
|
|
or just click on the language field) to look up the Pygments name.
|
|
|
|
* The links for opening code playgrounds are always constructed by concatenating
|
|
the provided URL prefix with the URL-encoded contents of the code block.
|
|
|
|
* 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.
|
|
|
|
If you have any trouble setting in setting up a code playground, please [contact
|
|
us](/help/contact-support) with details on what you're trying to do, and we'll
|
|
be happy to help you out.
|
|
|
|
## Related articles
|
|
|
|
[Math blocks][math-block], [spoiler blocks][spoiler-block], and [quote
|
|
blocks][quote-block] use similar fenced block syntax.
|
|
|
|
[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
|
|
|
|
[markdown]: /help/format-your-message-using-markdown
|
|
[math-block]: /help/format-your-message-using-markdown#latex
|
|
[quote-block]: /help/format-your-message-using-markdown#quotes
|
|
[spoiler-block]: /help/format-your-message-using-markdown#spoilers
|