Advanced Usage

Debug mode

Enable debug mode to write verbose logs to .medmark/logs/:

npx medmark --debug

Or answer yes to "Enable debug mode?" in the advanced options prompt. Logs include:

• Per-post metadata JSON
• Apollo state snapshots from scraped Medium pages
• Image download results

Exporting drafts

By default, draft posts (files starting with draft_) are skipped. To include them:

npx medmark --drafts

Drafts are identified by the filename prefix in the Medium export, not by the post's published status.

Drafts are always recorded in the json and ts registry outputs with draft: true; whether they reach the RSS feed and sitemap is controlled by registry.includeDrafts. See Content Registry.

Skipping specific files

Pass a comma-separated list of HTML filenames to ignore:

npx medmark --skip draft_old-post.html,another.html

Image strategies

REMOTE (default)

Keeps the original cdn-images-1.medium.com URLs. Zero download time, but images depend on Medium's CDN staying available.

LOCAL

Downloads all images into the path defined by imagePath in your template's getOptions(). Slower but self-contained.

getOptions() {
  return {
    imageStorageStrategy: 'LOCAL',
    imagePath: 'public/images',
  };
}

Embedded content

medmark resolves two kinds of embeds before converting the body:

• GitHub Gists are fetched and inlined as fenced code blocks, so the post stays readable without JavaScript.
• Tweets are fetched through Twitter's oEmbed endpoint and inlined as HTML.

Both require network access. Failures are recorded in conversion_report.json rather than aborting the run.

Handling reply posts

medmark automatically detects Medium "reply" posts (posts written in response to another post) and skips them. They are recorded in the conversion_report.json written to your output folder.

The conversion report

Every run writes conversion_report.json into the output folder with counts and failure reasons for posts, drafts, replies, images, and gists. It is the first place to look when a post did not come out as expected.

Programmatic API

medmark publishes its helpers and types so you can use them from your own scripts and templates:

const {
  frontMatterToYaml,
  buildDefaultRegistryEntry,
  serializeDefaultRegistry,
  logger,
  chalk,
} = require('medmark');

Workspace path constants (DEFAULT_MEDMARK_FOLDER_NAME, DEFAULT_MEDIUM_EXPORTS_FOLDER_NAME, DEFAULT_TEMPLATES_FOLDER_NAME, DEFAULT_MEDMARK_REGISTRY_FILENAME, and friends) are exported too.

Types

All the public interfaces ship with the package:

import type {
  MedmarkOptions,
  MedmarkRegistry,
  MedmarkRegistryEntry,
  MedmarkRegistryEntryContext,
  MedmarkRegistryFile,
  MedmarkRegistryOptions,
  MedmarkRegistrySiteOptions,
  MedmarkTemplate,
  MedmarkTemplateRenderOptions,
  MedmarkFrontMatter,
} from 'medmark';