GROWI Documentation

The VaultPathMapper converts GROWI page paths into deterministic git-tree file paths. This allows the vault to reconstruct file paths from page records without a reverse index.

Encoding Rules (v1)

Rules are applied in order:

1. Windows reserved characters: < > : " / \ | ? * are percent-encoded (e.g., < → %3C).
2. Control characters: U+0000–U+001F or U+007F are percent-encoded.
3. Leading/trailing spaces: Percent-encoded (%20).
4. Windows reserved filenames: Segments matching CON, PRN, AUX, NUL, COM0-9, or LPT0-9 (case-insensitive) are prefixed with _ (e.g., CON → _CON).
5. Case collision (reactive): If two paths in the same view differ only by case (e.g., /Foo and /foo), a __<hash8> suffix (first 8 chars of sha1(<path>.md)) is appended to the filename component.
6. Length limit: If a component exceeds 255 UTF-8 bytes, it is shortened (on character boundaries) and appended with a __<hash8> suffix.
7. Orphan pages: Paths /trash or starting with /trash/ are prefixed with _orphaned/.
8. Extension: .md is appended to the final component.

Key Behaviors

• Parent pages with children: A page with children does not use README.md. Instead, it uses <name>.md alongside a <name>/ directory.
• mapPrefix(pagePath): A variant that applies encoding and reserved-name prefixing but does not append .md or the __<hash8> suffix. Used for directory-only operations.

This extension implements the generic directives proposal. There are three types of directives:

1. Text Directives

Used within text lines. Syntax: :name[label]{attributes}. Example: :cite[smith04] or :abbr[HTML]{title="HyperText Markup Language"}.

2. Leaf Directives

Block-level directives without content. Syntax: ::name[label]{attributes} on its own line. Example: ::youtube[Video]{vid=01ab2cd3efg}.

3. Container Directives

Blocks that can contain other content. Syntax: :::name to open and ::: to close. Example:

:::spoiler
Content here
:::

Rules & Constraints:

• Naming: The name is required. It must start with a letter. Other characters can be alphanumeric, -, or _. - or _ cannot end a name.
• Labels: The [label] part is optional. :x and :x[] are equivalent. Labels can include text constructs like emphasis (:x[a *b* c]).
• Attributes: The {attributes} part is optional. Supports standard HTML attribute syntax.
  • Shortcuts: {#id} for {id=id} and {.class} for {class=class}.
  • Multiple classes: {.red .blue} or {class="red blue"} are both valid.
• Nesting: Containers can be nested using more colons (e.g., :::: to wrap :::) and must be closed with an equal or greater number of colons.
• Strictness: No whitespace is allowed between colons and the name, or between name/label/attributes. Labels and attributes cannot contain line endings.

When using useUnifiedMergeView, executing an Accept action in Editor 1 can cause changes to be applied twice. This happens because the change applied to the primaryDoc is synchronized back to Editor 1 via Yjs, which then attempts to apply it to the originalDoc again.

Solution: Using Yjs Transaction Origins

To prevent this, you must track the source of the transaction using a unique origin token.

1. When Accepting: Wrap the primaryDoc transaction with a specific origin.
2. During Synchronization: Check the transaction origin and skip processing if it matches the acceptance token.

Implementation Pattern:

// 1. Define a unique origin token
const SYNC_BY_ACCEPT_CHUNK = 'accept';

// 2. When performing the Accept action
primaryDoc.transact(() => {
  // ... apply changes ...
}, SYNC_BY_ACCEPT_CHUNK);

// 3. In the synchronization handler
if (event.transaction.origin === SYNC_BY_ACCEPT_CHUNK) {
  return; // Skip to prevent double application
}