#Syntax

Everything Markstrata renders, with the markdown you write beside what it turns into. The page is built through the web part's own pipeline, so each example below is rendered by the same code a SharePoint page runs: if something here stops working, this page stops showing it.

Where a feature is off by default, or belongs to a setting, the setting is named. The settings page covers the settings themselves, and linking documents covers what happens when one document points at another.

#Text

Punctuation is left exactly as it is written. A double hyphen stays a double hyphen and a straight quote stays straight, so --force in a sentence is still something a reader can copy and run. A bare address like https://example.com is turned into a link without being written as one.

An abbreviation is declared once and explains itself wherever it appears:

*[HTML]: HyperText Markup Language

#Headings and links

## A heading[a link](https://example.com)[a heading on this page](#text)

Headings get the same id GitHub gives them - lower case, punctuation dropped, spaces to hyphens, so ## Step 1: Install is #step-1-install - which means a link written against the page on GitHub lands here too. A heading also answers to the id it was given before this web part moved to GitHub's rule, so an anchor written against an older version still lands. With Heading link anchors on there is a # beside each heading to copy. A link to another site opens in a new tab.

An address written on its own becomes a link, including one that starts www. with no scheme in front of it. A bare file name does not: notes.md in a sentence is a file name, not an address.

#Wiki links

Off by default, under Wiki links.

A bare name resolves against the folder this document is in and nowhere else, which is not what Obsidian does with one. With a library file, a link to a page that is not there is marked. The whole of it.

#Embeds

![[picture.png]] puts the picture on the page, and takes the same sizes a markdown image does:

An embed of anything that is not a picture - another document, a PDF, a sound file - is rendered as a link marked as an embed rather than as the thing itself. Putting one on the page means fetching it, and nothing can be fetched while a document is being rendered.

#Naming a block

A paragraph, a list item, a quote or a table can be named, so a wiki link can point straight at it:

The build fails on a clean checkout. ^37066d| Service | Host ||---------|------|| Orders  | db01 |^hosts

The marker is not shown. [[Runbook#^37066d]] links to the block it names. A heading is named by its own words instead, [[Runbook#Rollback]].

#Lists

1. Ordered2. Second   1. Nested- Unordered  - Nested- [x] Done- [ ] Not done

A definition list:

Term: What it means

#Callouts

Three syntaxes, all rendered the same way. GitHub alerts:

> [!NOTE]> Useful information.

NOTE, TIP, IMPORTANT, WARNING and CAUTION.

Obsidian callouts, which take a title of their own and can fold. A - starts folded, a + starts open:

> [!tip] A title of your own> Any of Obsidian's types.> [!warning]- Folded to start with> Click the title to open it.

abstract, todo, success, question, failure, danger, bug, example, quote and info all work.

And the Wiki.js style older SharePoint web parts used:

> Still renders.{.is-success}

#Code

```typescript title="theme.ts"export const mode = 'dark';```

```ts:theme.ts is accepted as shorthand for the same thing.

A fence can override the page's own settings, and call out the lines that matter:

```python wrap nonumbers``````js {2,4-6}```

#Block height

short caps a block at about ten lines and medium at about twenty-five, and either scrolls inside rather than running down the page. full is the default and is a block as tall as its code.

```python short```

The caps are counted in lines rather than written in pixels, so they mean the same thing in every theme and follow the Code text size setting. Ten lines is roughly a paragraph of prose; twenty-five is over half a laptop window, so a capped block still has the text before and after it on screen with it.

There is a page setting for the default, Block height in the Code blocks group, so a page can make every block medium without touching the documents. A word on a fence beats it, the way wrap and numbers already do.

A capped block prints whole. There is no scrolling on paper, and printing the first ten lines of a listing and losing the rest is worse than printing all of it.

#Full size

A block with more to show than it is showing carries an Expand button beside Copy, and clicking the block opens it too. It opens in the same overlay a picture and a diagram use, uncapped, and Escape or a click outside closes it again. Selecting code still selects, and Copy still copies without opening anything.

Which blocks offer it is decided by measuring the rendered block rather than by reading the markdown: one capped by its height, one whose lines run past the column, or one longer than the window. A short block that already fits is left alone, because a control on every two line fence is clutter on the thing a document is mostly made of.

The Click a picture, diagram or code block to see it full size setting turns all three off together.

#Code from a URL

A fence with no body can say where its code is, and the block is filled in once that address answers:

```ts src="https://github.com/contoso/tools/blob/main/src/cache.ts#L10-L20"```

#L10-L20 and #L10 take those lines out of the fetched file, which is what makes this worth using: a runbook wants the twenty lines it is talking about, not the whole file. Both are what GitHub puts in the address bar when you click a line number, so the address you copy out of a browser is the address to paste. A github.com/.../blob/... link is translated to the raw host that returns the file, the same way a link to another document is.

The fetch happens after the document is drawn, so nothing waits on it. Until the address answers the block says which server it is waiting for, and if it never answers it says that instead of staying empty. The other server decides whether this page may read it at all: it has to allow cross-origin requests, and most do not. GitHub's raw host does.

What comes back is text. It is highlighted with the language on the fence and escaped exactly as a block typed into the document is, never rendered as markup. A fence that has both a body and a src shows the body.

#Tables

| Left | Centre | Right ||:-----|:------:|------:|| one | two | 3 |

A pipe inside a cell is written \|, which is the only escape a cell has, and works inside a code span as well as outside one. A row with too few cells is padded out to the table and a row with too many is trimmed to it.

^^ merges a cell with the one above it, and a doubled || mid-row runs a cell across the column to its right:

| Service | Host ||---------|------|| Orders  | db01 || ^^      | db02 || Both share a host || db02 |

#Images

An image that is a paragraph of its own can be clicked to see it full size.

#Diagrams and maths

```mermaidflowchart LR  A[Markdown] --> B[Rendered]```

Maths needs Math (KaTeX) on, and is written whichever way the editor it came from writes it:

A display block can follow straight on from the line that introduces it, and works inside a list item and inside a quote.

#Tags

With Tags on, #recipe and a nested #work/urgent are shown as tags rather than as words with a hash in front, the way a note written in Obsidian writes them. A tag holds letters, digits, _, - and /, has to contain at least one character that is not a digit, and cannot be joined onto the end of a word, so C# and #1984 are not tags. They are styled and nothing more: this web part cannot see the other documents in a library, so a tag that looked like a link would go nowhere.

Frontmatter tags are read as well, written any of the three ways:

---tags: [recipe, cooking]tags: recipe, cookingtags:  - recipe  - cooking---

#Comments

Ready to ship %%ask Dave first%%%%Not for the reader.%%

Anything between a pair of %% is left out of the page, inline or over several lines, the way Obsidian leaves it out. A marker with nothing closing it is shown as written rather than hiding the rest of the document.

#Footnotes

A claim[^1].[^1]: The support for it.

#The contents

[[toc]] on a line of its own puts a contents where you write it. A list of links to headings under a Contents heading counts too, and either is used in place of the generated one.

#Frontmatter

A block of metadata at the top of the file, the way Obsidian, Hugo and Jekyll write it, is taken off rather than rendered:

---title: Deploy runbookauthor: Opstags: [ops, sharepoint]---

title, author and tags are shown in the file footer. +++ works too.

#Raw HTML

Escaped unless Allow raw HTML in markdown is on. Callout titles are escaped either way. With the setting on the page is sanitised: formatting tags and embeds from a few known hosts are kept, and scripting is not. See Security.