Writing and formatting
Start with ordinary text. Add headings, mathematics, and references as you need them. Each example shows its source and the result produced by the same renderer used for papers.
A first example
Markdown is text with simple formatting marks. A line starting with ## becomes a section heading. Blank lines separate paragraphs. A pair of asterisks on either side makes words bold.
What you write
## A first example
A group describes **symmetry**.
We will study two examples.
- Rotations of a triangle
- Rotations of a square
What the reader sees
§1.1 A first example
A group describes symmetry. We will study two examples.
Rotations of a triangle
Rotations of a square
Use ### for a subsection. Put the paper’s title in Paper details, so you do not need to repeat it at the top of the text.
To link to a web page, write [link text](https://example.org). To display code, put it between lines containing three backticks. Adding a language name after the opening backticks tells the reader what kind of code it is.
What you write
Read the [Peerpedia help guide](/help/).
What the reader sees
Read the Peerpedia help guide.
What you write
```python
print(2 + 2)
```
What the reader sees
print(2 + 2)For instructions on saving and publishing, return to Publish your first note.
Write mathematics
Put mathematics inside single dollar signs to keep it in a sentence. Use double dollar signs on separate lines for an equation on its own.
What you write
The radius is $r$, so the area is
$$
A = \pi r^2.
$$
What the reader sees
The radius is , so the area is
Inside the dollar signs, use familiar LaTeX commands such as \frac{a}{b}, \sum, and \mathbb{R}. Do not add a document preamble or \begin{document}.
Only math code blocks receive automatic equation numbers. Double-dollar and backslash-bracket displays are unnumbered. Theorems share one counter; equations have a separate counter. Both restart at each chapter.
What you write
$$
a + b = b + a
$$
What the reader sees
Align several lines
Use \begin{aligned} and \end{aligned} inside a display formula or a math code block. Put & before the symbols to align and \\ between rows. A numbered block receives one number for the whole group.
What you write
```math {@eq:aligned}
\begin{aligned}
a+b &= c \\
x &= \frac{1}{2}
\end{aligned}
```
See @eq:aligned.
What the reader sees
See (1.1).
The editor’s Insert block menu inserts these wrappers for you. The next sections show how blocks also create references, statements, and captions.
Add chapters
Use a chapter when you want a new reading page, and a heading when you want a section within that page. A short note can stay on one page.
Open Chapters in the editor and choose Add chapter. Write its name in the first Markdown heading, such as # Introduction. Changing that heading also updates the chapter list. The up and down arrows change its place in the course.
Example course structure
- Symmetry introduces groups through rotations.
- Examples works through small groups.
- Exercises gives readers something to try.
Use the pencil icon beside a chapter while reading to edit only that chapter. Its draft and preview show that chapter alone. Submitting proposes a PR that preserves the other chapters. Use Edit paper to change several chapters or their order.
All chapters belong to the same paper. They are published together and share one bibliography. Use Files → Download all files to keep a local copy of the complete draft.
Link to sections and equations
A cross-reference is a link to a particular part of a paper. Rather than writing “see the equation above,” give the equation a label and refer to that label. Peerpedia fills in the displayed number and makes it clickable.
Let the editor insert the link
Place the cursor where you want the reference. Choose Insert reference, then In this paper. Select the chapter, section, equation, or statement you need. Chapters and headings appear automatically. To refer to a numbered equation or statement, give it a label first. Type @ to complete a label.
Write a label yourself
A label is a name you choose, such as eq:area. Put it inside {@…} on the item you want to link to. Write @ followed by the same name wherever you want to refer to it.
What you write
## Area of a circle {@sec:area}
```math {@eq:area}
A = \pi r^2.
```
See @sec:area for the explanation of @eq:area.
What the reader sees
The last sentence becomes links to the section and the numbered equation. The same syntax works across chapters. Use each label only once in the paper and keep it when moving or revising the text, so existing references continue to work.
Link to another Peerpedia paper
Choose Insert reference → Search Peerpedia. Find the work, then choose the whole work or a target within it. The inserted reference points to a fixed version, so a later edit does not silently change what you cited.
While reading, the link icon beside a chapter or section heading opens its reference window. Use the two overlapping squares beside an entry to copy it. Choose the ordinary link for sharing, or the Markdown reference for use in a Peerpedia note.
State a theorem or proof
Use a named block to set a statement apart from the surrounding explanation. For example, choose theorem from Insert block, then replace the sample text. A theorem can have a label just like an equation.
What you write
::: theorem {@thm:identity}
A group has exactly one identity element.
:::
::: proof
Suppose $e$ and $f$ are both identity elements.
Then $e = ef = f$.
:::
We use @thm:identity in the next example.
What the reader sees
Theorem 1.1
A group has exactly one identity element.
Suppose and are both identity elements. Then .
We use Theorem 1.1 in the next example.
The statement receives a number and can be linked. The proof is not numbered. The menu also offers lemma, proposition, corollary, definition, example, and remark blocks.
Cite another work
A bibliography collects the books, papers, and other sources you cite. Open Bibliography in the editor sidebar to edit the bibliography shared by all chapters.
Expand Add a reference to enter a title, authors, year, and link. Choose a short citation key, a name you will use to refer to that source. You can also import a YAML file or paste BananaMark bibliography entries. A bibliography code block in an article uses the same format.
A complete example
The example below has two parts. Put the YAML entry in Bibliography and the Markdown sentence in your chapter. Its citation key is euclidElements.
Then write a citation in the chapter by putting the key after @ inside square brackets.
What you write
Bibliography (YAML)
euclidElements:
type: book
author: Euclid
title: The Elements
year: 1956
publisher: Dover
Markdown
For a classical treatment, see [@euclidElements].
What the reader sees
The reader sees an author–year citation linking to the full entry. The shared bibliography appears at the end of the last chapter.
To point to a particular page or part, add it after a comma. To cite several sources together, separate their keys with a semicolon inside the brackets. Each key must have an entry in your bibliography. This example includes the entries it needs.
What you write
Bibliography (YAML)
euclidElements:
type: book
author: Euclid
title: The Elements
year: 1956
publisher: Dover
hatcher2002:
type: book
author: Hatcher, Allen
title: Algebraic Topology
year: 2002
publisher: Cambridge University Press
Markdown
Compare [@euclidElements, Book I] with a modern introduction [@hatcher2002, Chapter 0].
For both sources, see [@euclidElements; @hatcher2002].
What the reader sees
Compare [Euclid 1956, Book I] with a modern introduction [Hatcher 2002, Chapter 0].
For both sources, see [Euclid 1956; Hatcher 2002].
§References
Euclid (1956). The Elements. Dover.
Hatcher, Allen (2002). Algebraic Topology. Cambridge University Press.
Check that the source supports the statement you are making. A formatted citation is not a check of its contents.
Make a table
Separate columns with vertical bars. The row of dashes separates the headings from the body.
What you write
| Shape | Rotations |
| --- | --- |
| Triangle | 3 |
| Square | 4 |
What the reader sees
| Shape | Rotations |
|---|---|
| Triangle | 3 |
| Square | 4 |
Use Markdown tables directly. To give a table a numbered caption, put it inside a named environment such as ::: example (Table) {@table:results}.
Draw diagrams
Diagrams are written in the Markdown and appear as drawings in the reader. Start with a small example and check the preview before adding detail.
A commutative square
For a simple commutative diagram, use uppercase CD inside display mathematics.
What you write
$$
\begin{CD}
A @>f>> B \\
@VgVV @VVhV \\
C @>k>> D
\end{CD}
$$
What the reader sees
More control over arrows
Use a tikz code block for diagonal arrows or more elaborate labels. Include the environment inside the backticks.
What you write
```tikz
\begin{tikzcd}
A \arrow[r, "f"] \arrow[d, "g"'] & B \arrow[d, "h"] \\
C \arrow[r, "k"'] & D
\end{tikzcd}
```
What the reader sees
A general drawing
Use tikzpicture for shapes and paths. This example draws a circle and marks its radius.
What you write
```tikz
\begin{tikzpicture}
\draw (0,0) circle (1);
\draw[->] (0,0) -- (1,0) node[midway, above] {$r$};
\end{tikzpicture}
```
What the reader sees
If a drawing does not appear
Preview and publication use the same server compiler and cache. A new drawing may take a moment; an unchanged drawing reuses the cached result. Compilation errors must be corrected before publication.
Read the error beside the source if compilation fails. Start with the example above, then add your changes gradually. Basic TikZ commands and bundled libraries are supported. External files, image uploads, and arbitrary LaTeX packages are not supported.
Keep each drawing under 32 KB and the paper under 32 distinct drawings. Very slow drawings can time out. To show LaTeX code as text without drawing it, use a latex code block instead.
Check before submitting
- Read the preview as a reader would. Check each chapter, equation, and diagram.
- Open cross-references and check their destinations. Correct missing or repeated labels.
- Check bibliography entries and make sure each citation supports its claim.
- Use Review & publish for a new paper, or Review & submit PR for a revision. Check the title, authors, abstract, subject, and license as well as the text.
A paper can have up to 64 chapters. The combined Markdown and bibliography must fit within 1 MB. Formula errors and missing or duplicate reference labels must be corrected before submission. You can still save an incomplete draft.