Help:Contributing/code: Difference between revisions

From Wikibase
Jump to navigation Jump to search
Rewrite per cheatsheet style: strip translation markup, terse, real-world examples, practice the <code> carve-out (via update-page on MediaWiki MCP Server)
Line 1: Line 1:
<languages/>
Code appears on this wikibase in two places: as content on wiki pages and as data ([[Special:AddCodeSnippet|code-snippet items]]). This page covers the former.


<translate>
== Code blocks on wiki pages ==
<!--T:1-->
Code appears on this wikibase in two places: as content on wiki pages (this page) and as data (code-snippet items created via [[Special:AddCodeSnippet]]). This page covers the former.
</translate>
 
== <translate><!--T:2--> Code blocks on wiki pages</translate> ==


{| class="wikitable" style="width:100%"
{| class="wikitable" style="width:100%"
! What you want !! You type !! You get
|-
|-
! <translate><!--T:3--> Description</translate> !! <translate><!--T:4--> You type</translate> !! <translate><!--T:5--> You get</translate>
| Plain block — exactly as typed, no wiki markup, HTML escaped. Safe for logs and config pastes.
| &lt;pre&gt;[2026-08-19 14:32:01] wikibase.updater: entity Q42 updated&lt;/pre&gt;
| <pre>[2026-08-19 14:32:01] wikibase.updater: entity Q42 updated</pre>
|-
|-
| <translate><!--T:6--> Plain preformatted block — text exactly as typed, no wiki markup interpreted, HTML escaped. Safe for pasting raw code.</translate>
| Highlighted block — Pygments colours and a copy button.
| <translate><!--T:7--> &lt;pre&gt;print("hello")&lt;/pre&gt;</translate>
| &lt;syntaxhighlight lang="sparql"&gt;SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5&lt;/syntaxhighlight&gt;
| <pre>print("hello")</pre>
|-
| <translate><!--T:8--> Syntax-highlighted block — Pygments highlighting and a copy button (top right of the block).</translate>
| <translate><!--T:9--> &lt;syntaxhighlight lang="sparql"&gt;SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5&lt;/syntaxhighlight&gt;</translate>
| <syntaxhighlight lang="sparql">SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5</syntaxhighlight>
| <syntaxhighlight lang="sparql">SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5</syntaxhighlight>
|-
|-
| <translate><!--T:45--> Plain inline code — monospace within a sentence, no highlighting. Fine for short plain tokens without markup-significant characters.</translate>
| Plain inline code — monospace in a sentence, no colours. For short tokens with no markup-significant characters.
| <translate><!--T:46--> &lt;code&gt;latestId&lt;/code&gt;</translate>
| &lt;code&gt;latestId&lt;/code&gt;
| <code>latestId</code>
| <code>latestId</code>
|-
|-
| <translate><!--T:10--> Syntax-highlighted inline code — monospace within a sentence.</translate>
| Highlighted inline code — monospace in a sentence, with colours.
| <translate><!--T:11--> &lt;syntaxhighlight lang="python" inline&gt;print("hello")&lt;/syntaxhighlight&gt;</translate>
| &lt;syntaxhighlight lang="python" inline&gt;print("hello")&lt;/syntaxhighlight&gt;
| <syntaxhighlight lang="python" inline>print("hello")</syntaxhighlight>
| <syntaxhighlight lang="python" inline>print("hello")</syntaxhighlight>
|}
|}


<translate><!--T:44--> Anything inside <syntaxhighlight lang="html" inline><syntaxhighlight></syntaxhighlight> or <syntaxhighlight lang="html" inline><pre></pre></syntaxhighlight> will not be interpreted. They are rendered literally.</translate>
Anything inside <syntaxhighlight lang="text" inline><syntaxhighlight></syntaxhighlight> or <syntaxhighlight lang="text" inline><pre></syntaxhighlight> is rendered literally — wiki markup and HTML are not interpreted.


<blockquote><translate>
<blockquote>
<!--T:12-->
Be careful with <syntaxhighlight lang="text" inline><code></syntaxhighlight>: it does not escape HTML text such as &lt;, &gt; or &amp; inside it is read as markup. Use it for short plain tokens without those characters (<code>#</code>, <code>quarto render</code>, <code>latestId</code>); it is lighter to render. Use <syntaxhighlight lang="text" inline><syntaxhighlight lang="" inline></syntaxhighlight> when the snippet contains &lt;, &gt; or &amp; (it escapes content) or when you want colours. Never use <syntaxhighlight lang="text" inline><code></syntaxhighlight> for blocks — <syntaxhighlight lang="text" inline><pre></syntaxhighlight> or <syntaxhighlight lang="text" inline><syntaxhighlight></syntaxhighlight> instead.
Be careful with <tvar name="code"><syntaxhighlight lang="text" inline><code>…</code></syntaxhighlight></tvar>: it does not escape HTML: text such as <tvar name="lt"><syntaxhighlight lang="text" inline><</syntaxhighlight></tvar> or <tvar name="amp"><syntaxhighlight lang="text" inline>&</syntaxhighlight></tvar> inside it is read as markup. For short plain tokens with none of those characters (<tvar name="ex"><syntaxhighlight lang="text" inline>#</syntaxhighlight></tvar>, <tvar name="cmd"><syntaxhighlight lang="text" inline>quarto render</syntaxhighlight></tvar>) <tvar name="code2"><syntaxhighlight lang="text" inline><code></syntaxhighlight></tvar> is fine and lighter to render. Prefer <tvar name="shi"><syntaxhighlight lang="text" inline><syntaxhighlight inline></syntaxhighlight></tvar> whenever the snippet contains <tvar name="lt2"><syntaxhighlight lang="text" inline><</syntaxhighlight></tvar>, <tvar name="gt"><syntaxhighlight lang="text" inline>></syntaxhighlight></tvar> or <tvar name="amp2"><syntaxhighlight lang="text" inline>&</syntaxhighlight></tvar> (it escapes content) or you want syntax highlighting; never use <tvar name="code3"><syntaxhighlight lang="text" inline><code></syntaxhighlight></tvar> for blocks — use <tvar name="pre2"><syntaxhighlight lang="text" inline><pre></syntaxhighlight></tvar> or <tvar name="sh2"><syntaxhighlight lang="text" inline><syntaxhighlight></syntaxhighlight></tvar>.
</blockquote>
</translate></blockquote>


== <translate><!--T:13--> Which languages can be highlighted</translate> ==
== Which languages can be highlighted ==


<translate>
Any Pygments lexer alias works as the <code>lang</code> attribute — use the lowercase canonical name:
<!--T:14-->
Any Pygments lexer alias works as the <tvar name="lang"><syntaxhighlight lang="text" inline>lang</syntaxhighlight></tvar> attribute — use the lowercase canonical name:
</translate>


<translate>
* <code>sparql</code> — SPARQL queries (this wiki's query service)
<!--T:15-->
* <code>python</code>, <code>javascript</code>, <code>bash</code>, <code>sql</code>, <code>json</code>, <code>wikitext</code> — commonly used
* <tvar name="l1"><syntaxhighlight lang="text" inline>sparql</syntaxhighlight></tvar> — SPARQL queries (this wiki's query service)
* <tvar name="l2"><syntaxhighlight lang="text" inline>python</syntaxhighlight></tvar>, <tvar name="l3"><syntaxhighlight lang="text" inline>javascript</syntaxhighlight></tvar>, <tvar name="l4"><syntaxhighlight lang="text" inline>bash</syntaxhighlight></tvar>, <tvar name="l5"><syntaxhighlight lang="text" inline>sql</syntaxhighlight></tvar>, <tvar name="l6"><syntaxhighlight lang="text" inline>json</syntaxhighlight></tvar>, <tvar name="l7"><syntaxhighlight lang="text" inline>wikitext</syntaxhighlight></tvar> — commonly used
* Full list: [https://pygments.org/docs/lexers/ Pygments lexers] (use the alias column)
* Full list: [https://pygments.org/docs/lexers/ Pygments lexers] (use the alias column)
</translate>


== <translate><!--T:16--> Options for highlighted blocks</translate> ==
== Options for highlighted blocks ==
 
The options below are shown on this query — "items that are people":
 
<syntaxhighlight lang="sparql">
SELECT ?item WHERE {
  ?item wdt:P1 wd:Q6 .
}
</syntaxhighlight>


{| class="wikitable" style="width:100%"
{| class="wikitable" style="width:100%"
! Option !! You type !! You get
|-
|-
! <translate><!--T:17--> Option</translate> !! <translate><!--T:18--> You type</translate> !! <translate><!--T:19--> You get</translate>
| <code>line</code> — show line numbers
|-
| &lt;syntaxhighlight lang="sparql" line&gt;SELECT ?item WHERE {<br/>?item wdt:P1 wd:Q6 .<br/>}&lt;/syntaxhighlight&gt;
| <translate><!--T:20--> <tvar name="o1"><syntaxhighlight lang="text" inline>line</syntaxhighlight></tvar> — show line numbers</translate>
| <translate><!--T:21--> &lt;syntaxhighlight lang="sparql" line&gt;SELECT ?item WHERE {<br/>?item wdt:P1 wd:Q6 .<br/>}&lt;/syntaxhighlight&gt;</translate>
| <syntaxhighlight lang="sparql" line>SELECT ?item WHERE {
| <syntaxhighlight lang="sparql" line>SELECT ?item WHERE {
?item wdt:P1 wd:Q6 .
?item wdt:P1 wd:Q6 .
}</syntaxhighlight>
}</syntaxhighlight>
|-
|-
| <translate><!--T:22--> <tvar name="o2"><syntaxhighlight lang="text" inline>start="{int}"</syntaxhighlight></tvar> — first line number (with <tvar name="o2b"><syntaxhighlight lang="text" inline>line</syntaxhighlight></tvar>)</translate>
| <code>start="5"</code> — first line number (with <code>line</code>)
| <translate><!--T:23--> &lt;syntaxhighlight lang="sparql" line start="5"&gt;SELECT ?item WHERE {<br/>?item wdt:P1 wd:Q6 .<br/>}&lt;/syntaxhighlight&gt;</translate>
| &lt;syntaxhighlight lang="sparql" line start="5"&gt;SELECT ?item WHERE {<br/>?item wdt:P1 wd:Q6 .<br/>}&lt;/syntaxhighlight&gt;
| <syntaxhighlight lang="sparql" line start="5">SELECT ?item WHERE {
| <syntaxhighlight lang="sparql" line start="5">SELECT ?item WHERE {
?item wdt:P1 wd:Q6 .
?item wdt:P1 wd:Q6 .
}</syntaxhighlight>
}</syntaxhighlight>
|-
|-
| <translate><!--T:24--> <tvar name="o3"><syntaxhighlight lang="text" inline>highlight</syntaxhighlight></tvar> — highlight specific lines (comma-separated)</translate>
| <code>highlight="1,3"</code> — highlight specific lines (comma-separated)
| <translate><!--T:25--> &lt;syntaxhighlight lang="sparql" highlight="1,3"&gt;SELECT ?item WHERE {<br/>?item wdt:P1 wd:Q6 .<br/>}&lt;/syntaxhighlight&gt;</translate>
| &lt;syntaxhighlight lang="sparql" highlight="1,3"&gt;SELECT ?item WHERE {<br/>?item wdt:P1 wd:Q6 .<br/>}&lt;/syntaxhighlight&gt;
| <syntaxhighlight lang="sparql" highlight="1,3">SELECT ?item WHERE {
| <syntaxhighlight lang="sparql" highlight="1,3">SELECT ?item WHERE {
?item wdt:P1 wd:Q6 .
?item wdt:P1 wd:Q6 .
}</syntaxhighlight>
}</syntaxhighlight>
|-
|-
| <translate><!--T:26--> <tvar name="o4"><syntaxhighlight lang="text" inline>inline</syntaxhighlight></tvar> — render as inline code instead of a block</translate>
| <code>inline</code> — render as inline code instead of a block
| <translate><!--T:27--> &lt;syntaxhighlight lang="sparql" inline&gt;LIMIT&lt;/syntaxhighlight&gt;</translate>
| &lt;syntaxhighlight lang="sparql" inline&gt;LIMIT&lt;/syntaxhighlight&gt;
| <syntaxhighlight lang="sparql" inline>LIMIT</syntaxhighlight>
| <syntaxhighlight lang="sparql" inline>LIMIT</syntaxhighlight>
|-
|-
| <translate><!--T:28--> <tvar name="o5"><syntaxhighlight lang="text" inline>copy</syntaxhighlight></tvar> — adds a button that copies the block</translate>
| <code>copy</code> — add a button that copies the block
| <translate><!--T:29--> &lt;syntaxhighlight lang="sparql" copy&gt;SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5&lt;/syntaxhighlight&gt;</translate>
| &lt;syntaxhighlight lang="sparql" copy&gt;SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5&lt;/syntaxhighlight&gt;
| <syntaxhighlight lang="sparql" copy>SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5</syntaxhighlight>
| <syntaxhighlight lang="sparql" copy>SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5</syntaxhighlight>
|}
|}


<blockquote><translate>
<blockquote><code>inline</code> and <code>copy</code> are mutually exclusive.</blockquote>
<!--T:30-->
<tvar name="i"><syntaxhighlight lang="text" inline>inline</syntaxhighlight></tvar> and <tvar name="c"><syntaxhighlight lang="text" inline>copy</syntaxhighlight></tvar> are mutually exclusive.
</translate></blockquote>


<translate>
<!--T:31-->
Full parameter reference: [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight#Parameters SyntaxHighlight extension parameters] (official).
Full parameter reference: [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight#Parameters SyntaxHighlight extension parameters] (official).
</translate>


== <translate><!--T:32--> Differences from Markdown</translate> ==
== Differences from Markdown ==
 
{| class="wikitable" style="width:100%"
|-
! <translate><!--T:33--> Markdown habit</translate> !! <translate><!--T:34--> On this wiki</translate>
|-
| <translate><!--T:35--> Fenced code blocks (<tvar name="f1"><syntaxhighlight lang="text" inline>```</syntaxhighlight></tvar>)</translate>
| <translate><!--T:36--> There are no fenced blocks — <tvar name="f2"><syntaxhighlight lang="text" inline>```</syntaxhighlight></tvar> does nothing. Use <tvar name="f3"><syntaxhighlight lang="text" inline><pre></syntaxhighlight></tvar> or <tvar name="f4"><syntaxhighlight lang="text" inline><syntaxhighlight></syntaxhighlight></tvar>.</translate>
|-
| <translate><!--T:37--> Literal <tvar name="l1"><syntaxhighlight lang="text" inline>[[</syntaxhighlight></tvar> and <tvar name="l2"><syntaxhighlight lang="text" inline>{{</syntaxhighlight></tvar> inside a fenced block</translate>
| <translate><!--T:38--> In <tvar name="p"><syntaxhighlight lang="text" inline><pre></syntaxhighlight></tvar> and <tvar name="s"><syntaxhighlight lang="text" inline><syntaxhighlight></syntaxhighlight></tvar> wiki markup is not interpreted — <tvar name="l3"><syntaxhighlight lang="text" inline>{{</syntaxhighlight></tvar>, <tvar name="l4"><syntaxhighlight lang="text" inline>[[</syntaxhighlight></tvar> and quotes appear literally, which is what you want for code.</translate>
|}


<translate>
* No fenced blocks — <syntaxhighlight lang="text" inline>```</syntaxhighlight> does nothing here. Use <syntaxhighlight lang="text" inline><pre></syntaxhighlight> or <syntaxhighlight lang="text" inline><syntaxhighlight></syntaxhighlight>.
<!--T:39-->
* <syntaxhighlight lang="text" inline>[[</syntaxhighlight> and <syntaxhighlight lang="text" inline>{{</syntaxhighlight> inside <syntaxhighlight lang="text" inline><pre></syntaxhighlight> or <syntaxhighlight lang="text" inline><syntaxhighlight></syntaxhighlight> stay literal — which is what you want for code.
Blocks larger than 100&nbsp;kB lose highlighting automatically (a safety guard).
</translate>


== <translate><!--T:40--> House rules for code content</translate> ==
== House rules ==


<translate>
* Prefer <syntaxhighlight lang="text" inline><syntaxhighlight lang="…"></syntaxhighlight> for anything syntax-highlightable; <syntaxhighlight lang="text" inline><pre></syntaxhighlight> for config dumps and logs where colours add noise.
<!--T:41-->
* Blocks larger than 100 kB lose highlighting automatically (a safety guard).
* Prefer <tvar name="sh"><syntaxhighlight lang="text" inline><syntaxhighlight lang="…"></syntaxhighlight></tvar> for anything syntax-highlightable; use <tvar name="pre"><syntaxhighlight lang="text" inline><pre></syntaxhighlight></tvar> for config dumps and logs where colours add noise.
</translate>


== <translate><!--T:42--> See also</translate> ==
== See also ==


<translate>
<!--T:43-->
* [https://www.mediawiki.org/wiki/Help:Formatting MediaWiki syntax 101] (official)
* [https://www.mediawiki.org/wiki/Help:Formatting MediaWiki syntax 101] (official)
* [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight SyntaxHighlight extension] (official)
* [https://www.mediawiki.org/wiki/Extension:SyntaxHighlight SyntaxHighlight extension] (official)
* [https://pygments.org/docs/lexers/ Pygments lexers] — full language list
* [https://pygments.org/docs/lexers/ Pygments lexers] — full language list
* [[Help:Contributing]] — contributing to this wiki
* [[Help:Contributing]] — contributing to this wiki
</translate>

Revision as of 17:04, 19 August 2026

Languages: English · français · Esperanto

Code appears on this wikibase in two places: as content on wiki pages and as data (code-snippet items). This page covers the former.

Code blocks on wiki pages

What you want You type You get
Plain block — exactly as typed, no wiki markup, HTML escaped. Safe for logs and config pastes. <pre>[2026-08-19 14:32:01] wikibase.updater: entity Q42 updated</pre>
[2026-08-19 14:32:01] wikibase.updater: entity Q42 updated
Highlighted block — Pygments colours and a copy button. <syntaxhighlight lang="sparql">SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5</syntaxhighlight>
SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5
Plain inline code — monospace in a sentence, no colours. For short tokens with no markup-significant characters. <code>latestId</code> latestId
Highlighted inline code — monospace in a sentence, with colours. <syntaxhighlight lang="python" inline>print("hello")</syntaxhighlight> print("hello")

Anything inside <syntaxhighlight> or <pre> is rendered literally — wiki markup and HTML are not interpreted.

Be careful with <code>: it does not escape HTML — text such as <, > or & inside it is read as markup. Use it for short plain tokens without those characters (#, quarto render, latestId); it is lighter to render. Use <syntaxhighlight lang="…" inline> when the snippet contains <, > or & (it escapes content) or when you want colours. Never use <code> for blocks — <pre> or <syntaxhighlight> instead.

Which languages can be highlighted

Any Pygments lexer alias works as the lang attribute — use the lowercase canonical name:

  • sparql — SPARQL queries (this wiki's query service)
  • python, javascript, bash, sql, json, wikitext — commonly used
  • Full list: Pygments lexers (use the alias column)

Options for highlighted blocks

The options below are shown on this query — "items that are people":

SELECT ?item WHERE {
  ?item wdt:P1 wd:Q6 .
}
Option You type You get
line — show line numbers <syntaxhighlight lang="sparql" line>SELECT ?item WHERE {
?item wdt:P1 wd:Q6 .
}</syntaxhighlight>
SELECT ?item WHERE {
?item wdt:P1 wd:Q6 .
}
start="5" — first line number (with line) <syntaxhighlight lang="sparql" line start="5">SELECT ?item WHERE {
?item wdt:P1 wd:Q6 .
}</syntaxhighlight>
SELECT ?item WHERE {
?item wdt:P1 wd:Q6 .
}
highlight="1,3" — highlight specific lines (comma-separated) <syntaxhighlight lang="sparql" highlight="1,3">SELECT ?item WHERE {
?item wdt:P1 wd:Q6 .
}</syntaxhighlight>
SELECT ?item WHERE {
?item wdt:P1 wd:Q6 .
}
inline — render as inline code instead of a block <syntaxhighlight lang="sparql" inline>LIMIT</syntaxhighlight> LIMIT
copy — add a button that copies the block <syntaxhighlight lang="sparql" copy>SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5</syntaxhighlight>
SELECT ?item WHERE { ?item wdt:P1 wd:Q6 } LIMIT 5

inline and copy are mutually exclusive.

Full parameter reference: SyntaxHighlight extension parameters (official).

Differences from Markdown

  • No fenced blocks — ``` does nothing here. Use <pre> or <syntaxhighlight>.
  • [[ and {{ inside <pre> or <syntaxhighlight> stay literal — which is what you want for code.

House rules

  • Prefer <syntaxhighlight lang="…"> for anything syntax-highlightable; <pre> for config dumps and logs where colours add noise.
  • Blocks larger than 100 kB lose highlighting automatically (a safety guard).

See also