{"id":50593875,"url":"https://github.com/zenor0/mdship","last_synced_at":"2026-06-05T12:30:49.739Z","repository":{"id":355663933,"uuid":"1164629473","full_name":"zenor0/mdship","owner":"zenor0","description":"pack and ship your markdown","archived":false,"fork":false,"pushed_at":"2026-03-09T01:36:10.000Z","size":3476,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-04T19:03:34.954Z","etag":null,"topics":["cli","go","markdown","md","mermaid","pandoc","productivity","typst"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zenor0.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-23T09:59:47.000Z","updated_at":"2026-03-09T01:36:13.000Z","dependencies_parsed_at":"2026-05-04T19:03:56.452Z","dependency_job_id":null,"html_url":"https://github.com/zenor0/mdship","commit_stats":null,"previous_names":["zenor0/mdship"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/zenor0/mdship","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenor0%2Fmdship","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenor0%2Fmdship/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenor0%2Fmdship/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenor0%2Fmdship/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zenor0","download_url":"https://codeload.github.com/zenor0/mdship/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zenor0%2Fmdship/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33942426,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-05T02:00:06.157Z","response_time":120,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","go","markdown","md","mermaid","pandoc","productivity","typst"],"created_at":"2026-06-05T12:30:49.641Z","updated_at":"2026-06-05T12:30:49.728Z","avatar_url":"https://github.com/zenor0.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"![mdship banner](assets/mdship-banner.png)\n\n\u003c!-- \u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"assets/mdship-banner-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"assets/mdship-banner-light.png\"\u003e\n  \u003cimg alt=\"mdship banner\" src=\"https://user-images.githubusercontent.com/25423296/163456779-a8556205-d0a5-45e2-ac17-42d089e3c3f8.png\"\u003e\n\u003c/picture\u003e --\u003e\n\nDeliver your Markdown content anywhere in one command. mdship is a CLI tool and Go library for packaging Markdown context and converting to various formats via Pandoc and other tools.\n\n## Key features\n\n- **Resource Discovery and Packaging**: Automatically discover local and remote resources (images, PDFs, etc.) linked in your Markdown, download remote assets, and package them into a structured workspace for conversion.\n- **BibTex Citation Trimming**: Automatically extract and trim BibTeX entries for only the citations used in your document, keeping your bibliography lean and relevant.\n- **Built-in neat Typst/Word templates**: Use mdship's built-in Typst templates for quick and beautiful PDF generation, or create your own templates for custom styling.\n- **Mermaid Rendering**: Optionally render Mermaid diagrams to images before conversion, ensuring your diagrams look great in the final output.\n- **Conversion Pipeline**: Convert your Markdown to various formats (PDF, HTML, Typst, etc.) using a configurable pipeline that can include pre-processing steps (like Mermaid rendering) and post-processing steps (like Typst compilation).\n\n## Architecture\n\nTwo stages keep the system extensible:\n\n1) **pack**: discover resources/citations, download remote assets, trim BibTeX,\n   and build a minimal workspace.\n2) **convert**: run a conversion pipeline against packed markdown with predictable paths.\n\n## Workspace layout (pack output)\n\n```\n\u003cout-dir\u003e/\n  document.md\n  manifest.json\n  bibliography.bib        (optional)\n  assets/                 (local files copied here)\n  remote/                 (downloaded files)\n```\n\n## Installation\n\nInstall the CLI with Go:\n\n```bash\ngo install github.com/zenor0/mdship/cmd/mdship@latest\n```\n\nFor reproducible installs, prefer a tagged version instead of `latest`:\n\n```bash\ngo install github.com/zenor0/mdship/cmd/mdship@v0.1.0\n```\n\nMake sure your Go bin directory is on `PATH`:\n\n```bash\nexport PATH=\"$(go env GOPATH)/bin:$PATH\"\n```\n\nThen verify the installation and check which external tools are still needed:\n\n```bash\nmdship --version\nmdship check\n```\n\n## Requirements\n\n- Go 1.24+ (only required for `go install` or local development)\n- Pandoc on PATH\n- Mermaid CLI (`mmdc`) when Mermaid rendering is enabled (pack defaults to enabled)\n- Typst when compiling to PDF/PNG or using typst compile\n\n## Local checks before commit\n\nTo catch the same Go formatting, vet, lint, and test failures before pushing, run:\n\n```bash\nmake pre-commit\n```\n\nFor a fuller local pass that also checks `go mod tidy` drift and race tests, run:\n\n```bash\nmake ci-local\n```\n\nInstall the repo-pinned `golangci-lint` version used by CI with (it is stored under `.tools/bin`):\n\n```bash\nmake lint-install\n```\n\n`golangci-lint` is pinned in `.golangci-version`, and GitHub Actions reads that same file, so you only need to update one place when bumping the linter version. `make pre-commit` will auto-install or refresh that pinned version locally when missing or stale.\n\nIf you want Git to run the fast checks automatically before each commit, enable the repo hook once:\n\n```bash\ngit config core.hooksPath .githooks\n```\n\n## Usage\n\nCheck external dependencies:\n\n```bash\nmdship check\nmdship check --format json\n```\n\n`check` reports `pandoc`, `mmdc`, and `typst` so you can validate pack + convert toolchains up front.\n\n### Structured error output for integrations\n\nOn command failure, mdship still prints a human-readable error line to `stderr`.\nWhen `stderr` is non-interactive (pipe/file), mdship also appends one machine-readable line:\n\n```text\nMDSHIP_ERROR_JSON: {\"error\":{\"source\":\"cli\",\"code\":\"...\",\"kind\":\"...\",\"message\":\"...\",\"suggestions\":[...],\"details\":{...}}}\n```\n\nYou can force this behavior with `MDSHIP_ERROR_JSON=1` or disable it with `MDSHIP_ERROR_JSON=0`.\nCommon codes include `CLI_FLAG_INVALID`, `CLI_DEPENDENCY_MISSING`, `CLI_CONFIG_INVALID`,\n`CLI_PROFILE_INVALID`, `CLI_FILE_MISSING`, and `CLI_RESOURCE_MISSING`.\n\nPack a Markdown file:\n\n```bash\nmdship pack ./notes/example.md --out-dir ./mdship-out\n```\n\nBy default, `pack` only searches the input directory for relative resources (`--parent-depth=0`). Increase `--parent-depth` (or add `--resource-path`) when you intentionally want parent-directory lookup.\n\nClean previously generated workspace artifacts before writing fresh outputs:\n\n```bash\nmdship pack ./notes/example.md --out-dir ./mdship-out --clean\n```\n\nAdd resource paths and bibliography files:\n\n```bash\nmdship pack ./notes/example.md \\\n  --resource-path ./attachments \\\n  --bibliography ./refs/library.bib\n```\n\nOverride Pandoc markdown output settings during pack:\n\n```bash\nmdship pack ./notes/example.md --pandoc-arg=--wrap=preserve\n```\n\nConvert the packaged document:\n\n```bash\nmdship convert --input ./mdship-out/document.md --to typst\n```\n\nSelect a built-in conversion profile (e.g., Typst template preset):\n\n```bash\nmdship convert --input ./mdship-out/document.md --profile typst/default\n```\n\nUse Typst with a profile (embedded by default):\n\n```bash\nmdship convert --input ./mdship-out/document.md --to typst \\\n  --profile typst/default\n```\n\nUse a custom profile on disk:\n\n```bash\nmdship convert --input ./mdship-out/document.md --to typst \\\n  --profile /path/to/your/profile.yaml\n```\n\nBuilt-in profiles live under `modules/\u003cformat\u003e/profiles`. You can also point `--profile` at a local `profile.yaml` (or a profile directory).\n\nRelease binaries and `go install` builds include built-in profiles from embedded assets. You can verify them with `mdship profiles` after installation.\n\nList built-in profiles plus additional profile directories:\n\n```bash\nmdship profiles\nmdship profiles --profile-dir ./modules --profile-dir /path/to/custom/modules\nmdship profiles --profile-dir ./modules --verbose\nmdship profiles --profile-dir ./modules --format json\n```\n\n`profile.yaml` defines pandoc CLI args plus template metadata. `args` can be raw strings or structured YAML (unset fields are skipped):\n\n```yaml\nmeta:\n  name: Typst Default\n  alias: [default]\n  tags: [typst]\n  author: mdship\n  description: Default typst template profile.\nargs:\n  to: typst\n  standalone: true\n  template: profiles/default/template.typst\n  lua-filter:\n    - common/filters/html-br-linebreak.lua\n    - profiles/default/filters/callout-blocks.lua\n  metadata:\n    example: true\n```\n\nRules of thumb: keys map to Pandoc flags, `true` adds a flag, lists repeat flags, and `metadata`/`variable` accept maps.\n\nRender Mermaid blocks before conversion:\n\n```bash\nmdship convert --input ./mdship-out/document.md --to pdf --mermaid\n```\n\nConfigure a conversion chain explicitly:\n\n```bash\nmdship convert --input ./mdship-out/document.md --to pdf \\\n  --pipeline mermaid,pandoc:typst,typst-compile\n```\n\nKeep intermediate Typst output when compiling to PDF/PNG:\n\n```bash\nmdship convert --input ./mdship-out/document.md --to pdf --pipeline typst,typst-compile --typst-compile-keep\n```\n\nPass extra Pandoc arguments after `--`:\n\n```bash\nmdship convert --input ./mdship-out/document.md --to typst -- --template template.typst\n```\n\nShip a markdown file (pack + convert in a temp workspace):\n\n```bash\nmdship ship ./notes/example.md --to typst\n```\n\nWhen `ship` runs in default `file` mode and `--out` is omitted, output files are written to the current working directory (for example `./example.typ`).\n\nWhen `ship` writes outputs in `file` mode, existing conflicting files are protected by default (primary output + sidecars). In an interactive terminal, mdship prompts before overwrite; in non-interactive runs it fails safely.\n\nUse `--force` to overwrite without prompting:\n\n```bash\nmdship ship ./notes/example.md --to typst --force\n```\n\nWhen using `ship`, `--resource-path/-r` is also applied to the pack stage so external assets can be collected into the packaged workspace:\n\n```bash\nmdship ship ./notes/example.md --to typst --resource-path ./attachments\n```\n\nShip into a directory or zip archive:\n\n```bash\nmdship ship ./notes/example.md --to typst --ship-package dir --out ./dist\nmdship ship ./notes/example.md --to pdf --ship-package zip --out ./dist/example.zip\n```\n\n`ship` now preserves packaged sidecar resources (`assets/`, `remote/`) for text-like outputs (for example Typst/Markdown/HTML) so relative links keep working after export. It also writes a ship report with warnings/missing resources for downstream tooling:\n\n- file mode: `\u003coutput-base\u003e.ship-manifest.json`\n- dir/zip mode: `ship-manifest.json`\n\n`ship-manifest.json` and preflight reports now share the same JSON envelope (`version: 0.2.0`) so external callers can parse one schema for both dry-run checks and real shipments.\n\nRun a preflight check (pack-only) before full ship, and fail on any warnings/missing resources:\n\n```bash\nmdship ship ./notes/example.md --preflight --strict --report-out ./dist/preflight-report.json\n```\n\nUse `pack --strict` to fail when unresolved resources or warnings are detected:\n\n```bash\nmdship pack ./notes/example.md --strict --report-out ./mdship-out/preflight-report.json\n```\n\nOverride a specific markdown resource target without moving files into resource paths:\n\n```bash\nmdship ship ./notes/example.md --preflight --strict \\\n  --resource-map \"images/logo.png=/tmp/uploads/new-logo.png\"\n```\n\nUse a config file (YAML or JSON) to provide defaults:\n\n```bash\nmdship --config ./mdship.yaml pack ./notes/example.md\n```\n\nThe default config lives at `internal/config/default.yaml` (copy it as a starting point). CLI flags override config values when provided. For module layout conventions, see `docs/modules.md`.\n\nFor an implementation-based CLI input/output/error contract, see `docs/cli-contract.md`.\n\nProfiles can be declared in config and selected via `convert.profile` or `--profile`:\n\n```yaml\nconvert:\n  profiles:\n    typst/default:\n      path: typst/default\n  profile: typst/default\n```\n\nPrint the default or effective config:\n\n```bash\nmdship config\nmdship --config ./mdship.yaml config --effective\n```\n\n## Example\n\nSee `examples/example.md` for a minimal Markdown + asset + bibliography setup.\n\n## Contact\nFor questions, feedback, or contributions, please open an issue or reach out on GitHub Discussions.\n\n## License\nmdship is licensed under the MIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenor0%2Fmdship","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzenor0%2Fmdship","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzenor0%2Fmdship/lists"}