# FFS-MD for Visual Studio Code

Highlighting for **FFS-MD** — the FFS in-house Markdown dialect. This
extension does **not** replace VS Code's Markdown support; it *injects*
the FFS-specific tokens on top of the built-in Markdown grammar, so your
`.md` files keep all their normal Markdown highlighting and additionally
light up the FFS constructs.

## Features

Injected on top of `text.html.markdown`:

- **Block directives** `[IMAGE:…]`, `[VIDEO: …]`, `[SVG: …]`,
  `[LIST:…]` — the directive keyword, the inner path/label, and the
  `|` / `,` field separators each get their own scope. Prefixes are
  matched exactly (`[IMAGE:` has no space, `[VIDEO: ` has one).
- **Status marks** `(/) (x) (!) (?) (y) (n) (on) (off)` — only these exact
  literals, never an arbitrary `(word)`.
- **Emoji shortcodes** `:name:` (curated set plus ISO country-code flags).
- **Footnotes** `[^label]` references and `[^label]:` definitions.
- **`fson` fenced code**: inside a ` ```fson ` block the code is
  highlighted with the FSON grammar (`source.fson`) when the companion
  **FSON** extension (`vscode-fson`) is installed.

## Install

**Marketplace** (publisher **Fedem**): search *FFS-MD* in the Extensions
view, or

```bash
code --install-extension Fedem.vscode-ffsmd
```

**From a `.vsix`** (e.g. the one hosted on <https://fson.fedem.eu>): download
it, then `code --install-extension vscode-ffsmd-<version>.vsix`, or in VS
Code use the Extensions view → `⋯` → **Install from VSIX…**.

For FSON fenced-code colors, also install the **FSON** extension
(`Fedem.vscode-fson`).

For development, open this folder and press <kbd>F5</kbd>, then open a
`.md` file from `corpus/ffsmd/`.

## How the injection is scoped

The grammar's `injectionSelector` targets Markdown content and avoids
comments, strings, and already-embedded blocks. FFS directives are
left-injected (`L:`) so they take priority over Markdown's generic
`[link]` parsing. The injection only *adds* FFS token scopes — it never
overrides the base Markdown highlighting, so headings, emphasis, lists,
code, and VS Code's own YAML front-matter coloring all keep working
exactly as they do in a plain Markdown file.

## Formatting

FFS-MD has no canonical Markdown writer (the FFS renderer only produces
HTML), so this formatter is deliberately **conservative and
render-neutral**: `format(x)` renders to the same HTML as `x`. It normalizes
only what is provably safe and never rewrites Markdown structure.

What it normalizes:

- **FFS directive fields** — `[IMAGE:…]`, `[VIDEO: …]`, `[SVG: …]`,
  `[LIST:…]` have their `|`/`,`-separated fields trimmed to the compact
  canonical form (e.g. `[IMAGE: a | b | c ]` → `[IMAGE:a|b|c]`). This is
  exactly what the FFS renderer parses — it trims these fields itself — so
  the output is unchanged. Empty fields (`||`) and the exact prefixes
  (`[IMAGE:` no space, `[VIDEO: ` one space) are preserved.
- **Front-matter** — `key:   value` → `key: value` in the top-of-file
  `---` block.
- **Trailing whitespace** — removed (outside fenced code).
- **Blank-line runs** — three or more blank lines collapse to two.
- **Final newline** — the file ends with exactly one.

What it never touches: fenced-code content (kept byte-for-byte, including
inner whitespace and blank lines), GFM table rows, and all Markdown
structure — heading style, list markers, ordered numbering, emphasis
markers, blockquotes, indentation, and line wrapping.

Use it via the **FFS-MD: Format Document (FFS-MD)** command, or turn on
`ffsmd.format.enable` to make it the Markdown document formatter for
**Format Document** / format-on-save. It is off by default so it does not
affect every Markdown file automatically.

## Notes

- MD→FSON embedding (Markdown highlighted *inside* an FSON `|`-block) is
  intentionally out of scope; only `fson`→Markdown (fenced blocks) is
  handled here.
- Because this is an injection into every Markdown file, all `.md` files
  will recognize FFS tokens. If that is too broad for your workspace, you
  can disable the extension per-workspace.

## Development

```bash
npm install
npm test              # formatter tests + inline scope tests + corpus snapshots
npm run test:formatter   # formatter golden + corpus idempotency only
npm run test:update   # regenerate corpus snapshots after grammar changes
```

Tests use [`vscode-tmgrammar-test`](https://github.com/PanAeon/vscode-tmgrammar-test)
against the project's real `corpus/ffsmd/` files. The base Markdown and
FSON grammars used by the tests live under `test/grammars/`.

## License

MIT