Annotations
Annotations allow you to change how the code is displayed and also to add interactivity.
There are two ways to add annotations:
- using the codeblock metastring
- using comments inside the code
```py focus=2 mark=4[6:8]print(1)print(2)print(3)# focusprint(4)# link[1:8] http://foo.comprint(5)```
The current stable annotations are:
focus
: keep the targeted code bright while dimming the restmark
: add a background color to the targeted tokenswithClass
: add a class to the targeted codelink
: add links inside the codefrom
: include code from external files
First, let's see the syntax to target different parts of the code.
Metastring syntax
Some examples:
focus=1
selects the first line
focus=3:5
selects the range of lines 3 to 5
focus=7[7:9]
selects the columns 7 to 9 of the seventh line
focus=1,3:5,7[1:4,7:9]
combines the above examples
_10123456789012345678_10aaaaaaaaaaaaaaaaaa_10123456789012345678_10aaaaaaaaaaaaaaaaaa_10123456789012345678_10aaaaaaaaaaaaaaaaaa_10123456789012345678_10aaaaaaaaaaaaaaaaaa_10123456789012345678
Comment syntax
The syntax for comment annotations is slightly different.
// focus
selects the line after the comment
// focus(1,3)
selects the first and third line after the comment
// focus[3:8]
selects the columns 3 to 8 of the line after the comment
// focus(1,3[3:8])
selects the next line and the columns 3 to 8 of the third line after the comment
123456789012345678aaaaaaaaaaaaaaaaaa123456789012345678aaaaaaaaaaaaaaaaaa123456789012345678aaaaaaaaaaaaaaaaaa123456789012345678aaaaaaaaaaaaaaaaaa123456789012345678
Currently, we don't support comment syntaxes for several programming languages. The two supported are // comment
for C-style languages and the # comment
for python, bash, etc. In the future, all languages will be supported, you can follow this issue for updates.
focus
annotation
With the focus
annotation, you can highlight a specific part of the code and dim the rest.
The other functionality of the focus
annotation is to make sure the focused code is visible without the need to scroll:
focus=7
focus=2
focus=14
_15123456789012345678_15aaaaaaaaaaaaaaaaaa_15123456789012345678_15aaaaaaaaaaaaaaaaaa_15123456789012345678_15aaaaaaaaaaaaaaaaaa_15123456789012345678_15aaaaaaaaaaaaaaaaaa_15123456789012345678_15aaaaaaaaaaaaaaaaaa_15123456789012345678_15aaaaaaaaaaaaaaaaaa_15123456789012345678_15aaaaaaaaaaaaaaaaaa_15123456789012345678
mark
annotation
Sometimes you want to highlight code without dimming the rest. You can use the mark
annotation to do that.
You can use it to highlight lines:
Or you can use it inline, for tokens:
If you want to change the background or any other style, you can pass a CSS class to the annotation:
withClass
annotation
If you want to add a CSS class to a part of the code, without the default styles of mark
, you can use the withClass
annotation.
You can only use withClass
annotations as comments.
link
annotation
You can add links inside the code using the link
annotation.
The link URL could be absolute or relative.
function lorem() { // link[7:14] https://codehike.org let codehike = "be great"; // link[10:17] #mark-annotation return codehike}
You can only use link
annotations as comments.
from
annotation
Instead of writing the code inside the MDX file, you can use the from
annotation to import it from another file.
The path is relative to the MDX file.
If you want to import only a portion of the file, you can pass the starting and ending line number after the file path: