@mdwrk/mdwrkcom-content-pack 0.1.5

package/data/markdown/docs/getting-started/configuration.md

@@ -0,0 +1,82 @@
+---
+title: Client Configuration
+slug: getting-started/configuration
+section: Getting Started
+sectionOrder: 1
+order: 6
+toc: true
+date: 2026-05-02
+status: published
+author: CobyCloud
+excerpt: Theme Selection Open Settings -> Theme to switch between built-in theme families. Themes are contract-backed and flow through the editor, preview, export, and extension theme APIs.
+---
+
+## Theme Selection
+Open **Settings -> Theme** to switch between built-in theme families. Themes are contract-backed and flow through the editor, preview, export, and extension theme APIs.
+
+## Workspace Defaults
+- **Autosave**: Enabled by default for local-first persistence.
+- **Default View**: Choose Editor, Preview, or Split to match your writing style.
+- **Markdown Profiles**: Enable optional profile features without forking the renderer.
+- **Git Sync**: Provide credentials only when you want to push or pull.
+- **Extension Settings**: First-party and external extensions register their own schema-backed settings panels.
+
+## Lander Environment Variables
+The lander reads public navigation and metadata values at build time:
+
+| Variable | Purpose |
+| :--- | :--- |
+| `VITE_SITE_URL` | Canonical production origin used for sitemap and robots output. |
+| `VITE_APP_URL` | Installed app URL used by hero app-entry actions. |
+| `VITE_DEMO_URL` | URL for the live demo call to action. |
+| `VITE_GITHUB_REPO_URL` | Repository link used by the header GitHub action. |
+| `VITE_NPM_REPO_URL` | npm organization or package URL. |
+| `VITE_NPM_CLIENT_VERSION` | Published client package version shown in the hero. |
+| `VITE_NPM_ESM_CDN_URL` | ESM CDN URL used by package examples. |
+| `VITE_X_URL` | X profile URL shown in the footer. |
+| `VITE_COMMUNITY_URL` | Community destination shown in the footer. |
+
+Defaults are kept in the lander source so local builds remain usable without a full environment file.
+
+## Reverse Proxy
+Run the lander container on the internal Docker network and route traffic through your reverse proxy.
+
+## Package-Level Configuration
+If you consume the split packages directly:
+
+- `@mdwrk/markdown-editor-react` owns source-authoring behavior.
+- `@mdwrk/markdown-renderer-react` owns rendered markdown output.
+- `@mdwrk/theme-contract` owns theme token and bridge compatibility.
+
+## Metadata and Discovery
+The lander includes production metadata for:
+
+- canonical links
+- Open Graph previews
+- Twitter card previews
+- favicon assets
+- `robots.txt`
+- `llms.txt`
+- generated `sitemap.xml`
+
+Regenerate the sitemap during every production build so public routes stay aligned with the current Markdown docs.
+
+## Quick Reference
+
+Use this article to understand Client Configuration in the MdWrk Getting Started surface. Client Configuration explains how this MdWrk surface works in the current client and package system.
+
+Key concepts covered here:
+
+- local Markdown files
+- live preview
+- workspace organization
+- extension host contracts
+- theme portability
+
+Useful follow-up pages:
+
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [Markdown Preview Editor](/features/markdown-preview-editor)
+- [Editor Basics](/features/editor-basics)
+
+The MdWrk client ships with sensible defaults. These settings are part of the client and extension host surface, not the lander.

package/data/markdown/docs/getting-started/installation.md

@@ -0,0 +1,74 @@
+---
+title: Client Installation
+slug: getting-started/installation
+section: Getting Started
+sectionOrder: 1
+order: 1
+toc: true
+date: 2026-05-02
+status: published
+author: CobyCloud
+excerpt: Use the browser route for immediate access, the PWA route for an installable shell, local setup for development control, or standalone modules for package-level adoption.
+---
+
+## Installation Paths
+
+- [Use in a browser](/docs/getting-started/browser-use) when you want the fastest way to start writing without installing anything.
+- [Install as a PWA](/docs/getting-started/pwa-installation) when you want an app-like shell with browser-managed updates.
+- [Run locally from the repo or a local build](/docs/getting-started/local-setup) when you need a local development or self-hosted workflow.
+- [Use standalone modules](/docs/getting-started/standalone-modules) when you only want the reusable client, editor, or renderer packages.
+
+## Quick Choice Guide
+
+Use the browser route if you want immediate access with no setup.
+Use the PWA route if you want a dedicated window and installable shell.
+Use the local route if you need development control, local hosting, or a private self-managed deployment.
+Use standalone modules if you are embedding MdWrk surfaces into another product or internal tool.
+
+## Workspace Client Package
+
+The publishable client package is:
+
+```text
+@mdwrk/mdwrkspace
+```
+
+The split reusable packages start with:
+
+```text
+@mdwrk/markdown-editor-react
+@mdwrk/markdown-renderer-react
+@mdwrk/markdown-renderer-core
+```
+
+For package discovery and published versions, use the organization page:
+
+```text
+https://www.npmjs.com/org/mdwrk
+```
+
+## Notes
+
+Bundled extensions ship with the client build. External installable extensions follow the signed-manifest and trust-policy path documented in the extension docs.
+Published dates and statuses control whether installation docs appear on the lander at all, so draft installation notes can stay private until they are ready.
+
+## Quick Reference
+
+Use this article to understand Client Installation in the MdWrk Getting Started surface. Client Installation explains how this MdWrk surface works in the current client and package system.
+
+Key concepts covered here:
+
+- local Markdown files
+- workspace organization
+- extension host contracts
+- developer package reuse
+
+Useful follow-up pages:
+
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [Editor Basics](/features/editor-basics)
+- [Extension Platform](/docs/extensions/extension-platform)
+
+`mdwrk` is the client and package surface. The lander is only the documentation and release site.
+
+Choose the workflow that matches how you want to consume the workspace or packages.

package/data/markdown/docs/getting-started/local-setup.md

@@ -0,0 +1,94 @@
+---
+title: Local Setup
+slug: getting-started/local-setup
+section: Getting Started
+sectionOrder: 1
+order: 4
+toc: true
+date: 2026-05-02
+status: published
+author: CobyCloud
+excerpt: This path is for maintainers, internal adopters, and self-hosting operators who want more control than the browser or PWA flows provide.
+---
+
+## What it covers
+
+This path is for maintainers, internal adopters, and self-hosting operators who want more control than the browser or PWA flows provide.
+
+## Workspace prerequisites
+
+- Node.js `>=20 <23`
+- npm `>=10`
+- a local checkout of the repository
+
+## Basic local workflow
+
+1. Clone the repository.
+2. Install workspace dependencies.
+3. Start the surface you want to work on.
+
+```bash
+git clone https://github.com/groupsum/markdown_workspace.git
+cd markdown_workspace
+npm install --ignore-scripts
+```
+
+## Common local commands
+
+Run the client during development:
+
+```bash
+npm run dev:client
+```
+
+Run the lander during development:
+
+```bash
+npm run dev:mdwrkcom
+```
+
+Build the client:
+
+```bash
+npm run build -w apps/client
+```
+
+Build the lander:
+
+```bash
+npm run build -w apps/mdwrkcom
+```
+
+## Self-hosting notes
+
+The lander is a static site build. Set `VITE_SITE_URL` at build time so `robots.txt` and `sitemap.xml` use the correct public origin.
+
+```bash
+VITE_SITE_URL=https://mdwrk.com npm run build -w apps/mdwrkcom
+```
+
+The public lander is intended to sit behind a reverse proxy. Docker Compose in this repository must keep services internal-only rather than exposing ports directly.
+
+## When to choose another path
+
+Choose browser use or the PWA route when you just want to write.
+Choose standalone modules when you want package reuse without running the whole repository workspace.
+
+## Quick Reference
+
+Use this article to understand Local Setup in the MdWrk Getting Started surface. Local Setup explains how this MdWrk surface works in the current client and package system.
+
+Key concepts covered here:
+
+- local Markdown files
+- workspace organization
+- extension host contracts
+- developer package reuse
+
+Useful follow-up pages:
+
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [GitHub Sync](/docs/github-sync)
+- [PWA Installation](/docs/getting-started/pwa-installation)
+
+Use local setup when you want to run MdWrk from a repository checkout, create your own builds, or host the public surfaces yourself.

package/data/markdown/docs/getting-started/pwa-installation.md

@@ -0,0 +1,62 @@
+---
+title: PWA Installation
+slug: getting-started/pwa-installation
+section: Getting Started
+sectionOrder: 1
+order: 3
+toc: true
+date: 2026-05-02
+status: published
+author: CobyCloud
+excerpt: The Progressive Web App path keeps the MdWrk client in the web platform, but lets supported browsers install it as a dedicated app window.
+---
+
+## What it is
+
+The Progressive Web App path keeps the MdWrk client in the web platform, but lets supported browsers install it as a dedicated app window.
+
+## Typical install flow
+
+1. Open the MdWrk site in a PWA-capable browser.
+2. Use the browser's install action from the address bar, app menu, or share sheet.
+3. Launch the installed app from its icon or application list.
+
+## Best fit
+
+- frequent daily writing
+- a focused app window without full browser chrome
+- users who want updates delivered through the browser-managed install flow
+
+## Update behavior
+
+PWA updates are delivered through the normal web app update lifecycle. When a new build is ready, the client can prompt you to refresh into the updated version.
+
+## Storage and backup
+
+PWA mode still uses browser-managed local storage. Installability does not turn the app into a server-backed product, so exports and backups are still your responsibility.
+
+## When to choose another path
+
+Choose browser use when you do not want to install anything.
+Choose local setup when you need a repo checkout, local build scripts, or self-hosted control.
+Choose standalone modules when you need package-level reuse instead of the full workspace shell.
+
+## Quick Reference
+
+Use this article to understand PWA Installation in the MdWrk Getting Started surface. PWA Installation explains how this MdWrk surface works in the current client and package system.
+
+Key concepts covered here:
+
+- local Markdown files
+- live preview
+- workspace organization
+- privacy-first storage
+- extension host contracts
+
+Useful follow-up pages:
+
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [PWA Installation](/docs/getting-started/pwa-installation)
+- [Browser Use](/docs/getting-started/browser-use)
+
+Use the PWA route when you want the browser-hosted workspace with an installable app shell.

package/data/markdown/docs/getting-started/standalone-modules.md

@@ -0,0 +1,87 @@
+---
+title: Standalone Modules
+slug: getting-started/standalone-modules
+section: Getting Started
+sectionOrder: 1
+order: 5
+toc: true
+date: 2026-05-02
+status: published
+author: CobyCloud
+excerpt: MdWrk standalone modules expose the editor, renderer, extension contracts, theme tokens, and installable extension packages as reusable package surfaces.
+---
+
+## Primary packages
+
+The main package surfaces are:
+
+- `@mdwrk/mdwrkspace` for the full reusable workspace client
+- `@mdwrk/markdown-editor-react` for the editor surface
+- `@mdwrk/markdown-renderer-react` for the React renderer surface
+- `@mdwrk/markdown-renderer-core` for core parsing and rendering utilities
+
+## Full client package
+
+Install the reusable client package when you want the packaged workspace surface:
+
+```bash
+npm install @mdwrk/mdwrkspace
+```
+
+## Split editor and renderer packages
+
+Install the split packages when you only need one part of the experience:
+
+```bash
+npm install @mdwrk/markdown-editor-react @mdwrk/markdown-renderer-react
+```
+
+The editor React package depends on the editor core package internally.
+The renderer React package depends on the renderer core package internally.
+
+## ESM CDN example
+
+Load the published client directly from an ESM CDN:
+
+```html
+<div id="mdwrkspace-root"></div>
+<script type="module">
+  import { mountMdWrkSpace } from "https://esm.sh/@mdwrk/mdwrkspace";
+
+  const root = document.getElementById("mdwrkspace-root");
+  mountMdWrkSpace(root);
+</script>
+```
+
+## Package selection guidance
+
+Choose `@mdwrk/mdwrkspace` when you want the packaged workspace entrypoint.
+Choose `@mdwrk/markdown-editor-react` when authoring is the primary concern.
+Choose `@mdwrk/markdown-renderer-react` when rendering is the primary concern.
+Choose `@mdwrk/markdown-renderer-core` when you need lower-level parsing and HTML rendering utilities.
+
+## Related guidance
+
+For package-level configuration details, see the client configuration docs.
+For published package discovery, use:
+
+```text
+https://www.npmjs.com/org/mdwrk
+```
+
+## Quick Reference
+
+Use this article to understand Standalone Modules in the MdWrk Getting Started surface. Standalone Modules explains how this MdWrk surface works in the current client and package system.
+
+Key concepts covered here:
+
+- workspace organization
+- developer package reuse
+
+Useful follow-up pages:
+
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [Editor Basics](/features/editor-basics)
+- [Client Installation](/docs/getting-started/installation)
+
+Use standalone modules when you want MdWrk surfaces inside another application rather than the full workspace shell.

package/data/markdown/docs/github-sync.md

@@ -0,0 +1,51 @@
+---
+title: GitHub Sync
+slug: github-sync
+section: Integrations
+sectionOrder: 3
+order: 1
+toc: true
+date: 2026-05-02
+status: published
+author: CobyCloud
+excerpt: Repository Access Use a GitHub personal access token with the narrowest permissions your workflow requires. Store the token only when you want mdwrk to read from or write to a repository.
+---
+
+## Repository Access
+Use a GitHub personal access token with the narrowest permissions your workflow requires. Store the token only when you want mdwrk to read from or write to a repository.
+
+## Pull and Push
+Typical sync flow:
+
+1. Pull repository content into the local workspace.
+2. Edit documents in mdwrk.
+3. Review changes before pushing.
+4. Push intentionally when the local draft is ready to leave the browser.
+
+## Privacy Boundary
+Mdwrk does not need a backend server for normal editing. Content stays on the device unless you choose to sync, export, or otherwise send it somewhere else.
+
+## Operational Notes
+For production deployments, keep GitHub links current through `VITE_GITHUB_REPO_URL`. The public lander currently points to:
+
+```text
+https://github.com/groupsum/mdwrk
+```
+
+## Quick Reference
+
+Use this article to understand GitHub Sync in the MdWrk Integrations surface. GitHub Sync explains how this MdWrk surface works in the current client and package system.
+
+Key concepts covered here:
+
+- local Markdown files
+- workspace organization
+- developer package reuse
+
+Useful follow-up pages:
+
+- [Privacy-First Markdown Editor](/features/privacy-first-markdown-editor)
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [GitHub Sync](/docs/github-sync)
+
+GitHub sync is optional. The MdWrk client stays fully local until you connect a repository.

package/data/markdown/docs/product/desktop-app-boundary.md

@@ -0,0 +1,57 @@
+---
+title: Desktop App Boundary
+slug: product/desktop-app-boundary
+section: Features
+sectionOrder: 2
+order: 16
+toc: true
+date: 2026-05-06
+status: published
+author: CobyCloud
+displayAuthor: false
+excerpt: The desktop app boundary explains how MdWrk separates the browser workspace, Electron shell, preload bridge, and host filesystem access.
+---
+
+## Boundary Summary
+
+The MdWrk desktop app packages the same client workspace behind a native shell. The client remains the authoring surface, while the desktop shell owns host-only responsibilities such as native windows, file-open handoff, folder selection, and build targets.
+
+The boundary is visible in the repository:
+
+- `apps/client` owns the browser workspace experience.
+- `apps/desktop` owns Electron and native shell packaging.
+- `apps/desktop/src/preload.ts` exposes the narrow host bridge.
+- `apps/desktop/src/main.ts` owns native process behavior.
+
+## What Belongs In The Client
+
+The client owns Markdown editing, preview, settings, extension hosting, PWA version state, project selection, and browser-backed persistence. Code that can run in a normal web runtime should stay in the client or reusable packages.
+
+## What Belongs In The Desktop Shell
+
+The desktop shell owns native capabilities that the web runtime cannot provide directly:
+
+- opening Markdown files from the operating system
+- mounting a desktop folder as a workspace source
+- packaging Windows, Linux, macOS, and Android targets
+- exposing host APIs through the preload bridge
+
+Desktop features should cross into the client through explicit bridge methods instead of importing native modules into client code.
+
+## Operator Commands
+
+```bash
+npm run build:desktop
+npm run build:desktop:dist
+npm run build:desktop:win
+npm run build:desktop:linux
+npm run build:desktop:mac
+```
+
+The release scripts under `tools/ci` select the desktop or Android build path from the same workspace package graph.
+
+## Related Docs
+
+- [PWA Installation](/docs/getting-started/pwa-installation)
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [Extension Platform](/docs/extensions/extension-platform)

package/data/markdown/docs/product/developer-documentation.md

@@ -0,0 +1,52 @@
+---
+title: Developer Documentation
+slug: product/developer-documentation
+section: Features
+sectionOrder: 2
+order: 17
+toc: true
+date: 2026-05-03
+status: published
+author: CobyCloud
+displayAuthor: false
+excerpt: MdWrk developer documentation covers local setup, standalone packages, editor and renderer modules, extension authoring, theme packs, language packs, and package-level adoption paths.
+relatedApis: @mdwrk/mdwrkspace, @mdwrk/markdown-editor-react, @mdwrk/markdown-renderer-react, @mdwrk/extension-host
+---
+
+## Developer Entry Points
+
+Start with installation for adoption choices, local setup for repository work, standalone modules for embedding, and authoring docs for extensions, themes, and language packs.
+
+## Package Families
+
+The primary package families cover the client, editor, renderer, extension contracts, extension runtime, shared tokens, icons, i18n, and testing helpers.
+
+## Implementation Workflow
+
+Developers can run the repo locally, build package families, embed split editor and renderer packages, or author governed extensions that run in the MdWrk host.
+
+## Related Docs
+
+- [Local Setup](/docs/getting-started/local-setup)
+- [Standalone Modules](/docs/getting-started/standalone-modules)
+- [Authoring Overview](/docs/authoring/overview)
+
+## Quick Reference
+
+Use this article to understand Developer Documentation in the MdWrk Product surface. MdWrk developer documentation covers local setup, standalone packages, editor and renderer modules, extension authoring, theme packs, language packs, and package-level adoption paths.
+
+Key concepts covered here:
+
+- local Markdown files
+- workspace organization
+- extension host contracts
+- theme portability
+- developer package reuse
+
+Useful follow-up pages:
+
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [Editor Basics](/features/editor-basics)
+- [Extension Platform](/docs/extensions/extension-platform)
+
+MdWrk documents both the full workspace client and the reusable package stack behind it.

package/data/markdown/docs/product/extension-host.md

@@ -0,0 +1,52 @@
+---
+title: Extension Host
+slug: product/extension-host
+section: Features
+sectionOrder: 2
+order: 15
+toc: true
+date: 2026-05-03
+status: published
+author: CobyCloud
+displayAuthor: false
+excerpt: MdWrk includes a governed extension host with manifest, runtime, capability, trust, settings, command, view, diagnostics, theme, and language-pack surfaces.
+relatedApis: @mdwrk/extension-host, @mdwrk/extension-runtime, @mdwrk/extension-manifest, @mdwrk/extension-manager
+---
+
+## Host Contract
+
+The host exposes stable lifecycle and context contracts through extension packages. Extensions register commands, views, settings, and contributions through governed adapters instead of patching the client directly.
+
+## Runtime Controls
+
+The runtime handles activation, compatibility, persisted state, diagnostics, and trust policy enforcement. The manager extension gives users a visible operator console for installed extension behavior.
+
+## First-Party Extensions
+
+Current bundled surfaces include Extension Manager, Theme Studio, Language Pack Studio, Gemini Agent, Workspace Files, Git Operations, and catalog examples.
+
+## Related Docs
+
+- [Extension Platform](/docs/extensions/extension-platform)
+- [Extension Authoring](/docs/authoring/extensions)
+- [Theme Packs](/features/theme-packs)
+
+## Quick Reference
+
+Use this article to understand Extension Host in the MdWrk Product surface. MdWrk includes a governed extension host with manifest, runtime, capability, trust, settings, command, view, diagnostics, theme, and language-pack surfaces.
+
+Key concepts covered here:
+
+- workspace organization
+- extension host contracts
+- theme portability
+- developer package reuse
+- @mdwrk/extension-host
+
+Useful follow-up pages:
+
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [Extension Platform](/docs/extensions/extension-platform)
+- [Theme Packs](/features/theme-packs)
+
+The MdWrk client is the extension host for bundled and installable extension surfaces.

package/data/markdown/docs/product/local-first-markdown-workspace.md

@@ -0,0 +1,52 @@
+---
+title: Local-First Markdown Workspace
+slug: product/local-first-markdown-workspace
+section: Features
+sectionOrder: 2
+order: 11
+toc: true
+date: 2026-05-03
+status: published
+author: CobyCloud
+displayAuthor: false
+excerpt: MdWrk is a local-first Markdown workspace for projects, folders, files, preview links, themes, and extensions that should remain usable without forcing a cloud document model.
+relatedApis: @mdwrk/mdwrkspace, @mdwrk/extension-workspace-files, @mdwrk/extension-git-ops
+---
+
+## Workspace Shape
+
+The client presents projects, files, folders, editor panes, preview panes, settings, and extension surfaces inside one shell. Browser-managed storage is the default persistence layer, and desktop-backed file workflows can add host filesystem behavior where the shell supports it.
+
+## Project Operations
+
+Workspace operations include creating, renaming, deleting, and switching Markdown entries. Preview links can resolve against the current workspace so document sets can behave like connected knowledge and documentation projects.
+
+## Extension Surface
+
+Extensions can add managed views and commands without replacing the local-first editing model. Workspace Files and Git Operations are examples of package-ready surfaces for file-aware and repository-aware workflows.
+
+## Related Docs
+
+- [Local Setup](/docs/getting-started/local-setup)
+- [Extension Platform](/docs/extensions/extension-platform)
+- [GitHub Sync](/docs/github-sync)
+
+## Quick Reference
+
+Use this article to understand Local-First Markdown Workspace in the MdWrk Product surface. MdWrk is a local-first Markdown workspace for projects, folders, files, preview links, themes, and extensions that should remain usable without forcing a cloud document model.
+
+Key concepts covered here:
+
+- local Markdown files
+- live preview
+- workspace organization
+- privacy-first storage
+- extension host contracts
+
+Useful follow-up pages:
+
+- [Local-First Markdown Workspace](/features/local-first-markdown-workspace)
+- [Markdown Preview Editor](/features/markdown-preview-editor)
+- [Editor Basics](/features/editor-basics)
+
+MdWrk treats Markdown as a workspace, not a single textarea.