Documentation Anchors

Documentation Anchors

Documentation anchors are used to add static documentation content like Markdown text, multimedia, formatted tables, stylized equations, and code snippets right to your Archive. We give you access to powerful tools like Markdown, LaTeX, contextual macros (such as line number and file name), syntax-highlighted code snippets, and more. These can be used to explain your code, provide background material, and highlight important notes and interesting details.

You can create static content in single-line comments using the @doc anchor

# @doc This is plaintext

You can create static content in triple-quoted docstrings using the @blockdoc anchor

''' @blockdoc
Line 1 of plain text
Line 2 of plain text
Line 3 of plain text
'''

Documentation Content

Below, you can find a preview of all of the different types of static content that you can generate inside a documentation anchor.

Documentation Content - Detailed

Below, you can find detailed documentation on all of the different types of static content that you can generate inside documentation anchors.

Headers

You can create markdown headers in documentation anchors using the usual Markdown syntax:

SyntaxResult
# Heading 1Largest Header
## Heading 2Large Header
### Heading 3Medium Header
#### Heading 4Small Header
##### Heading 5Smallest Header

Example Usage:

''' @blockdoc
# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
'''
340340




Text

You can create plain text as well as stylized text using the usual Markdown syntax:

SyntaxResult
Plain textPlain Text
UnderlinedUnderlined Text
ItalicsItalicized Text
BoldedBolded Text

Example Usage:

''' @blockdoc
Plain Text
*Italics*
**Bold**
__Underlined__
'''
338338




You can hyperlink text with links to online files and websites using the usual Markdown syntax:

SyntaxResult
[Link](www.google.com)Hyperlink "Link" to go to www.google.com
[Link](./file.txt)Hyperlink "Link" to open file at relative path "./file.txt"
[Link](C://path/to/file.txt)Hyperlink "Link" to open file at absolute path "C://path/to/file.txt"
[Link](./folder)Hyperlink "Link" to open folder at relative path "./folder"
[Link](C://path/to/folder)Hyperlink "Link" to open folder at absolute path "C://path/to/folder"

Example Usage:

''' @blockdoc
Click this [Link](www.google.com) to go to Google.
'''
578578




Lists

You can create ordered and unordered lists using the usual Markdown syntax:

SyntaxResult
1. ItemOrdered List
* ItemUnordered List (bullet point)

Example Usage:

''' @blockdoc
1. Ordered list
    1. Ordered sublist
* Unordered list
    * Unordered sublist
'''
333333




Dividers

You can create a horizontal rule or section divider using the following syntax

SyntaxResult
***Horizontal Rule

Example Usage:

''' @blockdoc
Top
***
Middle
***
Bottom
'''
269269




Tables

You can create a table using the ordinary Markdown syntax:

SyntaxResult
| Col 1 | Col 2 |
| --- | --- |
| 1 | 2 |
Left-Aligned Table
| Col 1 | Col 2 |
| :--- :| :---: |
| 1 | 2 |
Center-Aligned Table
| Col 1 | Col 2 |
| ---: | ---: |
| 1 | 2 |
Right-Aligned Table

Example Usage:

''' @blockdoc
__Left-Aligned Table__
| Col 1 | Col 2 |
| --- | --- |
| 1 | 2 |
***
__Center-Aligned Table__
| Col 1 | Col 2 |
| :---: | :---: |
| 1 | 2 |
***
__Center-Aligned Table__
| Col 1 | Col 2 |
| ---: | ---: |
| 1 | 2 |
'''
333333




LaTeX

You can create stylized equations by surrounding LaTeX expressions with "$$". Artemis uses the MathJax interpreter for LaTeX processing. This supports most LaTeX commands, with some exceptions.

SyntaxResult
$$x^2 + 2x + 1$$Formatted LaTeX equation

Example Usage:

''' @blockdoc
$$\sum_{i=1}^{n} (x_i - \bar{x})(y_i - \bar{y})$$
$$\int_{a}^{b} x^2 dx$$
$$y = \beta_0 + \beta_1 x$$
'''
580580




Code

You can create syntax-highlighted code using the usual Markdown syntax:

SyntaxResult
`x = 3 + 2`In-line syntax-highlighted text
```
x = 3 + 2
```
Copyable syntax-highlighted code snippet

Example Usage:

''' @blockdoc
The line of code is `x = 2 + 3`
The code snippet is:
```
x = 2 + 3
```
'''
713713




Linked Code

You can display snippets of your own code as a syntax-highlighted code snippet using linked code.

First, insert @marker anchors throughout your code to extents of the code that you'd like to display with linked code.

# @marker start_marker
a = 1
b = 2
c = a + b
# @marker end_marker

Then, insert a @linkedcode marker and specify the two markers which define the code region to display:

# @linkedcode start=start_marker end=end_marker

Example Usage:

# @marker start_marker
a = 1
b = 2
c = a + b
# @marker end_marker

''' @blockdoc
This code demonstrates addition in Python:
# @linkedcode start=start_marker end=end_marker
'''
710710

Fields

Fields are in-line macros used to get contextual information. Default fields like %%__LINE__%% and %%__FILE__%% are substituted with the file name and line number in which the field appears. Custom fields like %%CUSTOM%% are substituted with the user-defined value for the field in their config files.

SyntaxResult
%%__LINE__%%This field will be replaced with the line number in which it appears
%%__FILE__%%This field will be replaced with the file name in which it appears
%%__CWD__%%This field will be replaced with the current working directory in which it appears
%%custom%%This field will be replaced with the custom value associated with the field "custom"

Example Usage:

''' @blockdoc
Line: %%__LINE__%%
File: %%__FILE__%%
Cwd: %%__CWD__%%
Custom field: %%author%%
'''
708708




Code Evaluation

Code evaluation is used to evaluate code and display the output of that evaluated code right inside your documentation. You can use evaluated code by inserting code expressions enclosed by << and >> into your documentation anchor.

SyntaxResult
<<"a" + "b">>Evaluates code and returns "ab"

Example Usage:

tokens = ["A", "B", "C"]
# @doc Token 1: <<tokens[0]>>
712712




Multimedia

Multimedia allows you to integrate multimedia right into your documentation using ordinary Markdown syntax.

Web Media

You may resize and display web media with the ordinary Markdown syntax

SyntaxResult
![Alt](www.website.com/image.png)Displays image found at www.website.com/image.png
![Alt](www.website.com/image.png =100x200)Displays image found at www.website.com/image.png and resizes to 100px x 200px
![Alt](www.website.com/image.png =100x*)Displays image found at www.website.com/image.png and resizes to 100px width and automatically determined height
![Alt](www.website.com/image.png =50%x*)Displays image found at www.website.com/image.png and resizes to 50% of the card width and automatically determined height

File Media

You may also resize and display file-based media by supplying the relative or absolute path of the media in place of the media's URL.

SyntaxResult
![Alt](./image.png)Displays image found at relative path ./image.png
![Alt](C://Users/Myself/image.png)Displays image found at local path C://Users/Myself/image.png

Example Usage:

''' @blockdoc
Image 1:
![Alt](https://www.artemisdevtool.com/Assets/images/logo_trim.png)
Image 2:
![Alt](https://www.artemisdevtool.com/Assets/images/logo_trim.png =65x36)
Image 3:
![Alt](https://www.artemisdevtool.com/Assets/images/logo_trim.png =30x*)
Image 4:
![Alt](https://www.artemisdevtool.com/Assets/images/logo_trim.png =10%x*)
'''
711711