{"id":28818449,"url":"https://github.com/kekyo/mark-deco","last_synced_at":"2026-01-20T16:45:58.620Z","repository":{"id":298617241,"uuid":"1000262951","full_name":"kekyo/mark-deco","owner":"kekyo","description":"A high-performance Markdown to HTML conversion library written in TypeScript.","archived":false,"fork":false,"pushed_at":"2025-06-12T01:30:19.000Z","size":344,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-12T02:32:07.610Z","etag":null,"topics":["card","frontmatter","html","markdown","mermaid","oembed","plugin","processor"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kekyo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2025-06-11T14:05:12.000Z","updated_at":"2025-06-12T01:30:09.000Z","dependencies_parsed_at":"2025-06-12T02:32:23.824Z","dependency_job_id":"0d1305a5-1055-4350-b200-7b89aeb8c0c1","html_url":"https://github.com/kekyo/mark-deco","commit_stats":null,"previous_names":["kekyo/mark-deco"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/kekyo/mark-deco","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fmark-deco","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fmark-deco/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fmark-deco/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fmark-deco/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kekyo","download_url":"https://codeload.github.com/kekyo/mark-deco/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kekyo%2Fmark-deco/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260616539,"owners_count":23036867,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["card","frontmatter","html","markdown","mermaid","oembed","plugin","processor"],"created_at":"2025-06-18T19:05:20.646Z","updated_at":"2026-01-20T16:45:58.613Z","avatar_url":"https://github.com/kekyo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MarkDeco\n\nFlexible Markdown to HTML conversion library.\n\n[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\n|Package|npm|\n|:----|:----|\n|`mark-deco`|[![npm version](https://img.shields.io/npm/v/mark-deco.svg)](https://www.npmjs.com/package/mark-deco)|\n|`mark-deco-cli`|[![npm version](https://img.shields.io/npm/v/mark-deco-cli.svg)](https://www.npmjs.com/package/mark-deco-cli)|\n\n[(Japanese is here/日本語はこちら)](./README_ja.md)\n\n## What is this?\n\nFlexible Markdown to HTML conversion library written in TypeScript.\nIt interprets GitHub Flavored Markdown (GFM) and outputs HTML.\nSupports frontmatter parsing, heading analysis, source code formatting, oEmbed/card/Mermaid graph rendering, and custom code block processing through plugin extensions.\n\n* Can be used to render HTML from Markdown input.\n* Simple interface makes it very easy to use.\n* Highly independent with minimal runtime requirements. Works in both Node.js and browser environments.\n* Built-in plugins support oEmbed, cards, and Mermaid.js.\n\n## Installation\n\n```bash\nnpm install mark-deco\n```\n\n## Basic Usage\n\nHere's the simplest usage example:\n\n```typescript\nimport { createMarkdownProcessor, createCachedFetcher } from 'mark-deco';\n\n// Create a memory-cached fetcher\nconst fetcher = createCachedFetcher('MyApp/1.0');\n\n// Create MarkDeco processor\nconst processor = createMarkdownProcessor({\n  fetcher\n});\n\n// Markdown to convert\nconst markdown = `---\ntitle: Sample Article\nauthor: John Doe\n---\n\n# Hello World\n\nThis is a test article.`;\n\n// Render HTML from Markdown input\nconst result = await processor.process(\n  markdown,\n  \"id\");     // ID prefix for HTML elements (described later)\n\n// Generated HTML\nconsole.log(result.html);\n// Extracted frontmatter information (described later)\nconsole.log(result.frontmatter);\n// Extracted heading information (described later)\nconsole.log(result.headingTree);\n```\n\nThis will render HTML like this:\n\n```html\n\u003ch1 id=\"id-1\"\u003eHello World\u003c/h1\u003e\n\u003cp\u003eThis is a test article.\u003c/p\u003e\n```\n\nA \"fetcher\" is an abstraction for external server access. It's primarily used by oEmbed and card plugins for external API calls and page scraping. See details below.\nThe argument passed to the fetcher is a user agent string, which is applied to HTTP request headers when accessing external servers.\n\nHTML converted by the MarkDeco processor is formatted in a readable manner. Advanced options allow fine-tuning of formatting conditions (described later).\n\n### Aborting Processor Operations\n\nWhile the MarkDeco processor engine itself doesn't access external servers, plugins may access external servers as needed (e.g., when using oEmbed APIs or performing page scraping).\n\nTo enable operation cancellation in such cases, pass an ECMAScript standard `AbortSignal` instance to notify cancellation signals:\n\n```typescript\n// Abort controller\nconst abortController = new AbortController();\n\n// ...\n\n// Convert Markdown to HTML\nconst result = await processor.process(\n  markdown, \"id\",\n  { // Specify processor options\n    signal: abortController.signal,   // Cancellation support\n  });\n```\n\nFor usage of `AbortController` and `AbortSignal`, refer to ECMAScript documentation.\n\n### Automatic Title Extraction\n\nBy default, MarkDeco copies the first base-level heading into `frontmatter.title` and removes that heading from the content. Adjust this with `headerTitleTransform`:\n\n```typescript\nawait processor.process(markdown, 'id', { headerTitleTransform: 'extract' });\n```\n\nUse `extract` to keep the heading while copying the title, `extractAndRemove` (default) to remove it, or `none` to skip the behaviour entirely.\n\n### Default Image Outer Class\n\nYou can assign a default CSS class to the parent paragraph (`\u003cp\u003e`) of Markdown images with `defaultImageOuterClassName`.\n\n```typescript\n// Add the .content-image and .shadow classes to the parent \u003cp\u003e tags\nawait processor.process(markdown, 'id', {\n  defaultImageOuterClassName: 'content-image shadow',\n});\n```\n\n### URL Resolver Hook\n\n`resolveUrl` lets you rewrite URLs generated from Markdown before HTML output.\nIt is called for Markdown links, images, reference definitions, and raw HTML attributes such as `href`, `src`, `srcset`, `poster`, `data`, `action`, `formaction`, `cite`, and `xlink:href`.\nThe hook always runs, so return the original URL when no change is needed.\nFor raw HTML, `context.tagName` and `context.attrName` identify the source attribute.\n\n```typescript\n// Prefix relative URLs\nawait processor.process(markdown, 'id', {\n  resolveUrl: (url, context) =\u003e {\n    if (/^(https?:)?\\/\\//.test(url) || url.startsWith('#')) {\n      return url;\n    }\n    return `/docs/${url}`;\n  },\n});\n```\n\n### CLI Interface\n\nAlthough MarkDeco is a library, a CLI interface is also available in the package that allows you to easily try out MarkDeco. This allows you to try out conversions without having to write code in TypeScript, or call it as an independent application from another code.\n\n```bash\n# Take Markdown from standard input and output HTML \n$ echo \"# Hello World\" | mark-deco\n```\n\nFor more information, see [CLI documentation](./docs/en/cli-application.md).\n\n----\n\n## Documentation\n\nMarkDeco has many useful features. For further details, please see below.\n\n- [Frontmatter Information Extraction](./docs/en/frontmatter-extraction.md) - Parse YAML frontmatter from Markdown files to extract metadata like title, author, tags, and publication date\n- [Heading ID Generation and Heading Information Extraction](./docs/en/heading-id-generation.md) - Automatically generate unique IDs for headings with hierarchical or content-based naming strategies\n- [Fetcher and Cache System](./docs/en/fetcher-and-cache-system.md) - External HTTP request management with configurable caching strategies for oEmbed APIs and page scraping\n- [Built-in Processing](./docs/en/built-in-processing.md) - oEmbed/card/Mermaid plugins and built-in code highlighting\n- [Creating Custom Plugins](./docs/en/creating-custom-plugins.md) - Develop custom plugins to extend Markdown processing with code block interceptors and unified ecosystem integration\n- [CLI Application](./docs/en/cli-application.md) - Command-line interface for batch processing Markdown files with configuration support and plugin control\n\n----\n\n## License\n\nUnder MIT.\n\n## Changelog\n\n* 0.1.0:\n  * First public release.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkekyo%2Fmark-deco","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkekyo%2Fmark-deco","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkekyo%2Fmark-deco/lists"}