M1hono Docs Assistant

Visual authoring tools for Markdown, VitePress, and M1hono-theme documentation projects. The extension combines Markdown-aware completions, hover docs, code lenses, and webview editors for the parts that are too heavy to edit comfortably by hand.

Current Release

• Version: 1.4.18
• VS Code engine: ^1.85.0
• Author: M1hono
• Repository: https://github.com/PickAID/PickAIDDocVSCodeExtension

What's New in 1.4.18

• Started platform core slice 1, moving frontmatter, component/plugin authoring reads, Smart Insert picks, insert commands, and prop tooling onto the resolved platform model with matching regression coverage.
• Added GitHub/VitePress-style Markdown alert blockquote templates such as > [!NOTE], available both from start-of-line Smart Insert and from selection wrapping.
• Fixed the LiteTree editor so normal property editing no longer throws the webview back to the top, while also expanding built-in icon suggestions and preserving marker-only rows such as //* comment.
• Expanded heading anchor CodeLens and explicit anchor editing to standard Markdown headings through ######, so deeper sections now get the same anchor workflow and jump resolution as top-level headings.

What It Covers

Capability Isolation

The extension is being separated into three capability layers instead of treating every docs workspace as a full M1hono project:

• Markdown only: generic Smart Insert, Mermaid, Markdown table editing, and Markdown-aware helpers
• VitePress only: internal doc-link intelligence, route-aware page suggestions, preview, and VitePress authoring helpers
• M1hono theme only: hero, sidebar, locale, component, plugin, and other theme-structured editors

The intended rule is simple:

• generic Markdown features should still work without VitePress recognition
• VitePress helpers should still work without M1hono recognition
• M1hono-specific tools should only appear when the theme layer is actually present

Markdown authoring

• capability-based Markdown, VitePress, and M1hono feature layers
• Component, plugin, and frontmatter completions for M1hono/VitePress docs
• layoutClass frontmatter suggestions now include preset values such as m-nav-layout and fullwidth-layout
• frontmatter metadata now includes details and the sidebar useChildrenCollapsed family
• Hover documentation for registered fields and props
• Quick fixes for unknown frontmatter and unknown component-like tags
• Shared Smart Insert wrapping support for Ruby {base:reading} formatting and text-wrappable containers
• Shared Smart Insert support for GitHub/VitePress alert blockquotes such as > [!NOTE], both as line inserts and selection wrappers
• Fenced code-block comment completions for VitePress // [!code ...] annotations
• Save-time protection for accidental raw angle brackets and unknown component-like tags in Markdown prose
• Smart insert workflow for components, assets, and supported Markdown structures
• File upload helpers for images and public assets
• Code lenses for page navigation links and heading anchor editing across Markdown headings from # through ######
• VitePress-aware internal link completion and resolved link jump behavior
• config-aware locale/root handling for custom project-config.ts source roots, locale links, and public paths

Visual editors

• Hero editor
• Frontmatter Config Editor
• Chart editor
• LiteTree editor with preserved pane scroll state, richer icon suggestions, and safer marker/comment round-tripping
• Bills editor
• MNavLinks editor
• Sidebar editor
• Sidebar folder editor
• Locale config editor
• Locale editor
• Team page editor
• Mermaid/diagram editor
• Markdown table editor

Project tooling

• Init Project is available from Command Palette globally and from the Explorer UI even in non-recognized workspaces
• Preview current Markdown page in the project VitePress dev server
• Set the preferred preview port per workspace from a command
• Initialize a new M1hono VitePress project in empty or non-empty folders, with optional workflow-file removal
• Initialize frontmatter with project-aware defaults
• Create doc pages and configured page templates
• Generate custom VitePress components
• Sync locale mappings
• Sync sidebar outputs
• Open or create structural /.sidebarrc.yml defaults
• Initialize repo settings for extension-managed behavior
• Audit runtime, manifest, and hover-doc locale coverage

Key Workflows

Frontmatter and page structure

Use the extension to edit:

• page metadata
• hero blocks
• features blocks
• sidebar navigation
• prev/next navigation overrides
• locale-driven configuration files

The hover system includes localized descriptions for page, sidebar, nav-links, and hero fields.

Workspace platform manifest

The first platform slice now resolves workspace-level authoring data through .pickAIDExtension/workspace-manifest.json at the active workspace root.

• it is separate from .pickAIDExtension/frontmatter.json
• built-in frontmatter fields, plugins, and Smart Insert containers are still present through the resolved platform model
• workspace contributions layer on top of that built-in model instead of replacing the extension's capability gates
• the current slice uses the manifest-backed model for frontmatter reads, component/plugin-backed completion-hover-code-lens surfaces, Smart Insert start-of-line component/plugin picks, insert component/plugin commands, and prop authoring flows

Repo frontmatter config

The repo frontmatter workflow is centered on .pickAIDExtension/frontmatter.json in the active docs root. The file is created automatically the first time you:

• run Frontmatter Config Editor
• use an unknown-frontmatter quick fix
• open the config JSON through the editor

Ways to open it:

• Command Palette: Frontmatter Config Editor
• Unknown key quick fix: Add "<key>" to repo frontmatter config
• Open .pickAIDExtension/frontmatter.json directly and use the inline Open Frontmatter Config Editor CodeLens/button at the top of the file

Verification scripts for the platform slice:

• npm run test:platform:model
• npm run test:platform:frontmatter
• npm run test:platform:components
• npm run test:platform:insert-commands
• npm run test:platform:prop-authoring
• npm run test:platform:smart-insert
• npm run test:platform:plugin-surfaces

What the editor writes:

• disabledKeys: hide built-in frontmatter keys from completion and hover
• fields: repo-specific custom fields
• when: optional exact-match conditions for conditional child fields
• acceptedTypes: optional extra value kinds when one field should accept more than one scalar type

The JSON intentionally stays minimal:

• field items do not write a description
• dotted keys support up to 3 levels, for example seo.openGraph.image
• when rules can depend on enum, boolean, string, or number values
• type stays the primary kind, while acceptedTypes can extend it, for example ["enum", "boolean"]

Example:

{
  "disabledKeys": ["hero"],
  "fields": [
    {
      "key": "someMode",
      "category": "meta",
      "type": "enum",
      "values": ["easy", "hard"],
      "default": "easy"
    },
    {
      "key": "somePanel",
      "category": "meta",
      "type": "object",
      "parentOnly": true
    },
    {
      "key": "somePanel.easyOnly",
      "category": "meta",
      "type": "string",
      "when": [
        {
          "key": "someMode",
          "equals": "easy"
        }
      ]
    }
  ]
}

Editor flow:

• create or select a field from the left list
• set the field key and type
• add when conditions only when the field should appear for a specific parent value
• save to write frontmatter.json

Multi-type example:

{
  "key": "metadata.mode",
  "category": "meta",
  "type": "enum",
  "acceptedTypes": ["enum", "boolean"],
  "values": ["doc", "kubejs", "modding", "mod"],
  "default": "doc"
}

Sidebar management

The sidebar tooling is Markdown-first and uses folder frontmatter together with structural /.sidebarrc.yml defaults. Repo frontmatter config in .pickAIDExtension/frontmatter.json remains separate and is not part of the sidebar runtime.

• reorder pages and folders
• control collapsed and hidden states
• use decimal priority values
• manage external links and generated groups
• edit folder-level config directly from sidebarIndex.md, index.md, and page frontmatter
• scaffold new sidebar folders with sidebarIndex.md and Catalogue.md
• configure folder-level useChildrenCollapsed rules with mode and depth
• define shared sidebar defaults in /.sidebarrc.yml
• sync generated sidebar output back into the VitePress project

Asset insertion

The asset workflow supports:

• uploading into tracked public folders
• inserting image and file paths into Markdown
• choosing existing public assets
• repo-level component-tag settings for unknown component-like tags

Localization maintenance

When translations drift, run the locale audit command to open a Markdown report that checks:

• runtime vscode.l10n bundle coverage
• manifest string coverage
• registry-backed hover documentation coverage
• zh-cn mirror drift against zh-hans

The report is exported to .pickAIDExtension/reports/locale-coverage.md inside the current workspace.

Commands

The extension currently contributes 44 commands. Main commands include:

• Open Preview
• Set Preview Port
• Hero Editor
• Chart Editor
• LiteTree Editor
• Bills Editor
• MNavLinks Editor
• Edit Sidebar
• Edit Sidebar Folder
• Locale Config Editor
• Locale Editor
• Team Page Editor
• Diagram Editor
• Markdown Table Editor
• Smart Insert
• Sync Sidebar
• Audit Locale Coverage
• Initialize Repo Settings
• Open Sidebar RC

Init Project

The project init flow now supports two scaffold structures and workflow-file control:

• Docs subdirectory: clones the template into docs/ under the selected folder
• Root structure: clones the template directly into the selected folder
• Non-empty folders: allowed after an explicit confirmation when files already exist in the selected target
• Keep workflow files: default behavior, preserves template .github automation files
• Remove workflow files: strips .github during scaffold cleanup
• Skill workflow: the template skill-artifact workflow is always removed during init, even when other workflow files are kept

The init cleanup still removes copied template repository metadata such as .git and .gitmodules, but it now preserves skills/.

Configuration

When a workspace is VitePress-based but not an M1hono theme project, the extension can still resolve VitePress paths and locale roots from either:

• .vitepress/config/project-config.ts
• root-level VS Code settings fallback for the docs source path and locale structure

Project Layout

The current codebase is organized around small command and service modules:

src/
  commands/        VS Code command entry points
  data/            static registries for components, plugins, and frontmatter
  providers/       completions, hovers, code actions, code lenses, diagnostics
  services/        editor/runtime logic grouped by domain
  services/asset/  public asset browsing and upload helpers
  services/chart/  chart editor parsing and webview support
  services/hero/   hero editor runtime and field metadata
  services/navlinks/
  services/frontmatter/
  services/capabilities/
  services/sidebar/
  services/sidebarFolder/
  services/teamPage/
  services/table/

Build

npm install
npm run compile

Test

npm run test
npm run test:phase1:capabilities
npm run test:phase1:markdown-links
npm run test:phase2:frontmatter
npm run test:phase2:navigation
npm run test:phase2:sidebarrc
npm run test:project-activation
npm run test:project-config
npm run test:sidebar-folder-editor
npm run test:local
npm run test:locale-config-editor

Localization

The extension uses VS Code vscode.l10n.

• l10n/bundle.l10n.json: source strings
• l10n/bundle.l10n.zh-hans.json: Simplified Chinese
• l10n/bundle.l10n.zh-cn.json: Simplified Chinese mirror
• package.nls.json: manifest strings
• package.nls.zh-hans.json: localized manifest strings

License

MIT