ArTchie Studios
ArTchie-Bedder-Suite / Docs / Folio

Folio Guide — read markdown in the Editor

Plain English first. Sharp edges after.

1. What this is / is not

Folio turns a .md file into a page inside Unity. Preview or source. Inspector preview when you select a markdown asset. Double-click opens it. Fully native Unity Editor APIs. Markdown is parsed and rendered in C# that ships with this package. No Node. No extras required.

It is not Scribe (comment banners / sidecar writers). It is not Charter (game plans). It is not Atlas (code map). Folio only reads markdown that is already in the project (or that you Browse…). Soft friend of Scribe: after Document Selection, Scribe may hint Open with Folio / Open when Folio is installed. Folio never requires Scribe.

2. Open it

Everything hangs under:

ArTchie / Folio / …

Job Click
Open the Folio window (selected .md if any) ArTchie / Folio / Open
Same window (alias) ArTchie / Folio / Viewer
Context menu on a markdown asset Assets / Folio / Open
Same, asset right-click Assets / Open in Folio
Fast path Double-click a .md / .markdown / .mdown in the Project window

If a README still says Folio / … without the ArTchie/ prefix, the README is stale — trust the menu in Unity.

3. First five minutes

  1. Make sure com.artchie.folio is in the project (Packages/unity-folio or a file: entry in Packages/manifest.json). Open Unity. Wait for import. Check the Console for red errors.
  2. In the Project window, find the package sample: Packages/…/unity-folio/Docs/SAMPLE.md (or your own Assets/…/*.md).
  3. Double-click the file — or select it and click ArTchie / Folio / Open.
  4. You should see a rendered page (headings, table, code, tasks). Status bar shows the path and a word count.
  5. Toggle Preview / Source. Leave Follow on and click another .md in the Project window — the page swaps. Use Browse… if the file is outside the usual pick path.

That is enough. Inspector preview and Scribe’s open hint are extras — never required to read a page.

4. The meat

Window chrome

  • Preview — rendered CommonMark-ish + GFM subset (see below).
  • Source — read-only raw markdown (mono font). Toggle sticks in EditorPrefs (Folio.ShowSource).
  • Follow — when on (default), Project selection of another markdown file reloads the page. Pref: Folio.FollowSelection.
  • Browse… — OS file picker for .md. Paths under the project root become project-relative; absolute paths outside still load from disk.
  • Markdown object field — drop or pick a markdown asset. Non-markdown objects get a toast: Pick a .md or .markdown file.
  • Empty state: title No markdown file open + HelpBox (pick / drop / Browse…) + miniLabel (ArTchie / Folio / Open · Viewer or double-click). Status: No file · pick a .md or Browse….

Inspector

Selecting a markdown TextAsset shows Open in Folio, path · word count, and a capped scroll preview. Other TextAssets keep a plain text inspector (name, size, dump).

What it renders

Good enough for READMEs, CHANGELOGs, kit docs, and Scribe sidecars:

  • YAML front matter → compact meta strip
  • ATX headings #–######, setext titles
  • Paragraphs, hard breaks, autolinks
  • *italic* **bold** ***both*** ~~strike~~ `inline code`
  • Fenced code + language tag; quiet keyword wash for C# and JavaScript (no highlight library)
  • Lists, nested lists, ordered lists, task lists (- [ ] / - [x])
  • Blockquotes, pipe tables (alignment), thematic breaks
  • Links: http(s) / mailto: → browser; relative .md → Folio; Assets/ and Packages/ paths → ping + select
  • Images from a project path, or http when Unity can load the texture; alt text if missing

Soft friend: Scribe

Scribe writes Markdown sidecars (FileStem.md beside the script, or under Docs/). If Folio is present, Scribe probes Folio.FolioWindow by reflection and may log Open with Folio / Open after a successful Document write. Folio does not call Scribe. Neither kit hard-depends on the other.

Native-only lock

  • Package: com.artchie.folio · Unity 2021.3+ · asmdef Folio.Editor
  • Allowed: AssetDatabase, EditorWindow, UIToolkit, IMGUI, ScriptedImporter, OnOpenAsset, Application.OpenURL (plus UnityWebRequest for optional http images)
  • package.json has no dependencies other than Unity. No Node for Editor use.

Importer note (Unity 6+)

On Unity 6+, Unity owns a native .md importer, so Folio’s ScriptedImporter registers only markdown / mdown. Open paths are file-path-based — double-click, menus, and preview still work for .md. Older Unity registers .md / .markdown / .mdown.

Double-click hook

OnOpenAsset resolves the active selection path (id-free) so Unity 6 EntityId changes do not break open. Returns true only for markdown paths Folio owns.

5. Common stuck

  1. Menus say Folio / … without ArTchie/ — stale README or old sample copy. This package’s Docs/SAMPLE.md uses ArTchie / Folio / Open. Trust Unity: ArTchie / Folio / ….
  2. I don’t see ArTchie / Folio — package not imported, asmdef error, or wrong project. Check Console and Packages/manifest.json for com.artchie.folio.
  3. Double-click opens a raw dump / external app — another handler may be first, or the asset is not treated as markdown. Use ArTchie / Folio / Open, Assets / Open in Folio, or the Inspector Open in Folio button.
  4. Empty window / “No file” — nothing selected, or selection is not .md / .markdown / .mdown. Select SAMPLE.md, drop a file in the field, or Browse….
  5. Follow does nothing — Follow toggle is off, or you clicked a non-markdown asset. Turn Follow on and pick another .md.
  6. Scribe wrote a sidecar but no Folio hint — Folio not installed, or reflection probe failed. Open the .md yourself with ArTchie / Folio / Open. Folio is never required for Scribe.
  7. Image missing / link does nothing useful — broken relative path, missing texture, or http load failed. Alt text shows when the image cannot load; Assets/ / Packages/ links need a real loadable asset.

6. For pros

Package + entry points

com.artchie.folio · Folio.Editor
Folio.FolioWindow.OpenFile(path)     — open / focus window on a project or disk path
Folio.FolioWindow.OpenFromMenu()     — selection if markdown, else empty window
Folio.FolioMarkdown.Parse(text)      — FolioDocument (blocks, WordCount, Source)
Folio.FolioPreview.Build(doc, path, onLink)
Folio.FolioPaths.IsMarkdown / FromSelection / Read / Resolve / HandleLink

EditorPrefs

Folio.FollowSelection   (bool, default true)
Folio.ShowSource        (bool, default false)

Soft reflection (Scribe → Folio)

Scribe looks up type Folio.FolioWindow across loaded assemblies. No asmdef reference either way. Hint only after a successful Document write when the type exists.

Design bounds (do not invent)

Folio is an Editor markdown viewer. Do not document a second store kit, a required Node pipeline, or Folio-as-authoring-IDE. Scribe writes; Folio reads. Charter / Atlas / Anvil / Rivet do not need Folio.

Canonical base

artchie-RECONCILED-20260822-2107. Package README + this Guide. Demo page: Docs/SAMPLE.md.

Kit When you want it
Suite Map Which ArTchie pile does what · Guides/Guide-Suite-Map.md
Scribe Write comment banners + Markdown sidecars; may hint Open with Folio
Charter Game plans (soft pile with Scribe + Folio; Folio just reads any .md)
Atlas Project map / search — not a markdown viewer
Anvil / Rivet Project health · daily Editor chores
Bedder In-player IDE
ArTchie AI Companion chat (optional Atlas map tools; not Folio)

Double-click a .md. Toggle Preview. Scribe’s hint is optional sugar on top.

Source in the box: Assets/ArTchie Studios/ArTchie-Suite/com.artchie.folio/Documentation/Guide-Folio.md