mirror of https://github.com/zulip/zulip.git
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.
This commit is contained in:
Alya Abbott
Tim Abbott
parent
c60609efeb
commit
279f7b1c8d
|
|
@ -176,4 +176,4 @@ block][code-block]).
|
|||
|
||||
[chat-zulip-org]: ../contributing/chat-zulip-org.md
|
||||
[production-help]: https://chat.zulip.org/#narrow/stream/31-production-help
|
||||
[code-block]: https://zulip.com/help/format-your-message-using-markdown#code
|
||||
[code-block]: https://zulip.com/help/code-blocks
|
||||
|
|
|
|||
|
|
@ -188,7 +188,7 @@ help](https://chat.zulip.org/#narrow/stream/31-production-help) in the
|
|||
server](../contributing/chat-zulip-org.md) for best-effort help.
|
||||
Please include the relevant error output from the above logs in a
|
||||
[Markdown code
|
||||
block](https://zulip.com/help/format-your-message-using-markdown#code)
|
||||
block](https://zulip.com/help/code-blocks)
|
||||
in any reports.
|
||||
|
||||
### Rolling back to a prior version
|
||||
|
|
|
|||
|
|
@ -7,7 +7,7 @@
|
|||
code. Zulip code blocks that are <z-link-markdown-help>tagged with a programming language</z-link-markdown-help> will have
|
||||
a button visible on hover that allows you to open the code block in the code playground site.
|
||||
{{#*inline "z-link-repl"}}<a href="https://replit.com/" target="_blank" rel="noopener noreferrer">{{> @partial-block}}</a>{{/inline}}
|
||||
{{#*inline "z-link-markdown-help"}}<a href="/help/format-your-message-using-markdown#code" target="_blank" rel="noopener noreferrer">{{> @partial-block}}</a>{{/inline}}
|
||||
{{#*inline "z-link-markdown-help"}}<a href="/help/code-blocks" target="_blank" rel="noopener noreferrer">{{> @partial-block}}</a>{{/inline}}
|
||||
{{/tr}}
|
||||
</p>
|
||||
<p>
|
||||
|
|
@ -27,7 +27,7 @@
|
|||
<div class="new-playground-form wrapper">
|
||||
<div class="settings-section-title">
|
||||
{{t "Add a new code playground" }}
|
||||
{{> ../help_link_widget link="/help/add-a-custom-playground" }}
|
||||
{{> ../help_link_widget link="/help/code-blocks#code-playgrounds" }}
|
||||
</div>
|
||||
<div class="alert" id="admin-playground-status"></div>
|
||||
<div class="control-group">
|
||||
|
|
|
|||
|
|
@ -70,7 +70,7 @@
|
|||
With a single click, one can easily copy code block
|
||||
contents to the clipboard or transfer the contents
|
||||
to
|
||||
an <a href="/help/add-a-custom-playground">external
|
||||
an <a href="/help/code-blocks#code-playgrounds">external
|
||||
code playground</a> that can run the code.
|
||||
</p>
|
||||
</div>
|
||||
|
|
|
|||
|
|
@ -128,17 +128,17 @@ Import your existing organization from [Slack](/help/import-from-slack),
|
|||
|
||||
### Collaborate on code and formulas
|
||||
|
||||
[Markdown code blocks](/help/format-your-message-using-markdown#code)
|
||||
[Markdown code blocks](/help/code-blocks)
|
||||
with syntax highlighting make it easy to discuss code, paste an error
|
||||
message, or explain a complicated point. Native LaTeX support provides
|
||||
the same benefits when talking about math.
|
||||
|
||||
You can also instantly copy a code block to your clipboard or transfer
|
||||
it to an [external code playground](/help/add-a-custom-playground) to
|
||||
it to an [external code playground](/help/code-blocks#code-playgrounds) to
|
||||
interactively run and debug the code.
|
||||
|
||||
If your community primarily uses a single programming language,
|
||||
consider setting a default language for syntax highlighting.
|
||||
consider setting a [default code block language](/help/code-blocks#default-code-block-language).
|
||||
|
||||
### Permalink to conversations.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,72 +0,0 @@
|
|||
# Add a custom playground
|
||||
|
||||
{!admin-only.md!}
|
||||
|
||||
Code playgrounds allow users to open the contents of a [code
|
||||
block][code-block] in an external playground of your choice by
|
||||
clicking a widget that appears when hovering over the code block.
|
||||
|
||||
Code playgrounds can be configured for any programming language (the
|
||||
language of a code block is determined by the logic for syntax
|
||||
highlighting). You can also use a custom language name to implement
|
||||
simple integrations. For example, a playground for the language
|
||||
`send_tweet` could be used with a "playground" that sends the content
|
||||
of the code block as a Tweet.
|
||||
|
||||
[code-block]: /help/format-your-message-using-markdown#code
|
||||
|
||||
### Add a custom playground
|
||||
|
||||
{start_tabs}
|
||||
|
||||
{settings_tab|playground-settings}
|
||||
|
||||
1. Under **Add a new playground**, enter a **Name**, **Language** and
|
||||
**URL prefix**.
|
||||
|
||||
1. Click **Add playground**.
|
||||
|
||||
{end_tabs}
|
||||
|
||||
## Walkthrough with an example
|
||||
|
||||
Consider the following example.
|
||||
|
||||
* Name: `Rust playground`
|
||||
* Language: `Rust`
|
||||
* URL prefix: `https://play.rust-lang.org/?edition=2018&code=`
|
||||
|
||||
When composing a message `rust` can be mentioned as the syntax highlighting
|
||||
language in the code blocks.
|
||||
|
||||
~~~
|
||||
``` rust
|
||||
fn main() {
|
||||
// A hello world Rust program for demo purposes
|
||||
println!("Hello World!");
|
||||
}
|
||||
```
|
||||
~~~
|
||||
|
||||
The user would then get a on-hover option to open the above code in the playground
|
||||
they had previously configured.
|
||||
|
||||
## 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 syntax highlighting language in a code block
|
||||
is internally mapped to these human-readable Pygments names.
|
||||
E.g: `py3` and `py` are mapped to `Python`. We are working on implementing a
|
||||
typeahead for looking up the Pygments name. Until then, one can use
|
||||
[this Pygments method](https://pygments-doc.readthedocs.io/en/latest/lexers/lexers.html#pygments.lexers.get_lexer_by_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.
|
||||
|
||||
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.
|
||||
|
|
@ -0,0 +1,139 @@
|
|||
# Code blocks
|
||||
|
||||
Zulip supports the standard [Markdown syntax][markdown] for code
|
||||
blocks:
|
||||
|
||||
~~~
|
||||
Inline: `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 codeblocks, or just indent the code 4 or more
|
||||
spaces.
|
||||
|
||||
A widget in the upper-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 speficied 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`. We are working on implementing a typeahead for looking up the
|
||||
Pygments name. Until then, one can use [this Pygments method][get_lexer_by_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
|
||||
|
|
@ -109,18 +109,9 @@ def fib(n):
|
|||
|
||||
You can also use `~~~` to start codeblocks, or just indent the code 4 or more spaces.
|
||||
|
||||
Zulip supports syntax highlighting for hundreds of languages, and a
|
||||
typeahead will pop up when you start typing after the ` ``` `. If you can't
|
||||
find your language, search for it [here](https://pygments.org/docs/lexers/)
|
||||
and try the **short names** listed for the lexers for your language.
|
||||
|
||||
Organization administrators can also configure a default syntax
|
||||
highlighting language. In this configuration, one can use ````text`
|
||||
to display content without any syntax highlighting.
|
||||
|
||||
Hovering over a Zulip code block reveals buttons to copy the code or
|
||||
open it in one of the organization's configured [custom code
|
||||
playgrounds](/help/add-a-custom-playground).
|
||||
See the main [code blocks article](/help/code-blocks) for details on
|
||||
[syntax highlighting](/help/code-blocks#language-tagging), [code
|
||||
playgrounds](/help/code-blocks#code-playgrounds), and other features.
|
||||
|
||||
## LaTeX
|
||||
~~~
|
||||
|
|
|
|||
|
|
@ -37,6 +37,7 @@
|
|||
* [Mention a user or group](/help/mention-a-user-or-group)
|
||||
* [Edit or delete a message](/help/edit-or-delete-a-message)
|
||||
* [Message a stream by email](/help/message-a-stream-by-email)
|
||||
* [Code blocks](/help/code-blocks)
|
||||
* [Add GIFs in your message](/help/animated-gifs-from-giphy)
|
||||
* [Create a poll](/help/create-a-poll)
|
||||
|
||||
|
|
@ -140,7 +141,6 @@
|
|||
* [Add custom emoji](/help/add-custom-emoji)
|
||||
* [Configure authentication methods](/help/configure-authentication-methods)
|
||||
* [Add a custom linkifier](/help/add-a-custom-linkifier)
|
||||
* [Add a custom playground](/help/add-a-custom-playground)
|
||||
* [Message retention policy](/help/message-retention-policy)
|
||||
* [SAML authentication](/help/saml-authentication)
|
||||
|
||||
|
|
|
|||
|
|
@ -64,7 +64,7 @@ link_mapping = {
|
|||
],
|
||||
"playground-settings": [
|
||||
"Manage organization",
|
||||
"Playgrounds",
|
||||
"Code playgrounds",
|
||||
"/#organization/playground-settings",
|
||||
],
|
||||
"profile-field-settings": [
|
||||
|
|
|
|||
|
|
@ -2629,7 +2629,7 @@ paths:
|
|||
additionalProperties: false
|
||||
description: |
|
||||
Event sent to all users in a Zulip organization when the
|
||||
set of configured [code playgrounds](/help/add-a-custom-playground)
|
||||
set of configured [code playgrounds](/help/code-blocks#code-playgrounds)
|
||||
for the organization has changed.
|
||||
|
||||
**Changes**: New in Zulip 4.0 (feature level 49).
|
||||
|
|
@ -6986,7 +6986,7 @@ paths:
|
|||
operationId: add_realm_playground
|
||||
tags: ["server_and_organizations"]
|
||||
description: |
|
||||
Configure [code playgrounds](/help/add-a-custom-playground) for the organization.
|
||||
Configure [code playgrounds](/help/code-blocks#code-playgrounds) for the organization.
|
||||
|
||||
`POST {{ api_url }}/v1/realm/playgrounds`
|
||||
|
||||
|
|
@ -7042,7 +7042,7 @@ paths:
|
|||
operationId: remove_realm_playground
|
||||
tags: ["server_and_organizations"]
|
||||
description: |
|
||||
Remove a [code playground](/help/add-a-custom-playground) previously
|
||||
Remove a [code playground](/help/code-blocks#code-playgrounds) previously
|
||||
configured for an organization.
|
||||
|
||||
`DELETE {{ api_url }}/v1/realm/playgrounds/{playground_id}`
|
||||
|
|
@ -7450,7 +7450,7 @@ paths:
|
|||
Present if `realm_playgrounds` is present in `fetch_event_types`.
|
||||
|
||||
An array of dictionaries where each dictionary describes a
|
||||
[code playground](/help/add-a-custom-playground) configured for this Zulip organization.
|
||||
[code playground](/help/code-blocks#code-playgrounds) configured for this Zulip organization.
|
||||
|
||||
**Changes**: New in Zulip 4.0 (feature level 49).
|
||||
realm_user_groups:
|
||||
|
|
|
|||
Loading…
Reference in New Issue