Skip to main content

md2zhihu

中文介绍在: md2zhihu-中文介绍.

Converts markdown into a single-file version without local asset dependencies, which can be directly imported into zhihu.com or other social platforms with a single click.

md imported
original
converted

Usage

md2zhihu DOES NOT support Windows: Issue: no module termios. Use it remotely with GitHub Action:

1. Use it remotely with GitHub Action:

This is the recommended method since you do not need to install anything locally. Only git is required.

Add the action configuration into the git repository where your markdown files are located for conversion: .github/workflows/md2zhihu.yml:

name: md2zhihu
on: [push]
jobs:
  md2zhihu:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - uses: actions/checkout@v7
      - uses: drmingdrmer/md2zhihu@v0.22
        env:
          GITHUB_USERNAME: ${{ github.repository_owner }}
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

A push runs this workflow. It converts each markdown file and saves the result in _md2zhihu. It pushes that directory to a branch named after the branch that was pushed, with -md2zhihu added. A push to main creates main-md2zhihu:

Branch main:

▾ _posts/
    2013-01-31-jobq.markdown
    2013-01-31-resource.markdown
    ...

Branch main-md2zhihu:

▾ _posts/
    2013-01-31-jobq.md
    2013-01-31-resource.md
    ...
▾ _md2zhihu/
    jobq.md
    resource.md
    ...

For example, one of the converted single-file examples has all its assets stored remotely on gitee.com, so it can be safely used anywhere without worrying about handling its dependency assets.

There are two ways to get the converted markdown files:

  • git fetch and git merge the branch main-md2zhihu.
  • Or access this branch directly on the web: single-file example

Action Options for md2zhihu

  • pattern:

    File pattern to convert

    required: False default: **/*.md

  • output_dir:

    Directory to store converted markdown

    required: False default: _md2zhihu

  • asset_repo:

    Specify the git repo for asset storage.

    The converted markdown will reference images in this repo. Supported providers include github.com and gitee.com. When this option is absent, assets are pushed to the current repo: https://github.com/{{ github.repository }}.git.

    To push assets to gitee.com:

    1. On gitee.com, create an access token at https://gitee.com/personal_access_tokens, to enable pushing assets to gitee.com; The token must enable projects privileges.

    2. Add a secret to the GitHub markdown repository that contains your gitee.com username and token (e.g., GITEE_AUTH=drdrxp:abcd...xyz) at https://github.com/<username>/<repo>/settings/secrets/actions.

    3. Set asset_repo to the gitee.com repo push URL with the auth token, such as:

      - uses: drmingdrmer/md2zhihu@main
        with:
          pattern: _posts/*.md
          asset_repo: https://${{ secrets.GITEE_AUTH }}@gitee.com/<owner>/<repo>.git
      

    required: False default: the local repo: 'https://github.com/${{github.repository}}.git'

  • asset_branch:

    The branch name in which assets are stored.

    required: False default: ${{ github.ref_name }}-md2zhihu-asset

  • output_branch:

    The branch name to which output markdowns are stored. Set this to "" to disable push, in which case, user commit and push it manually.

    required: False default: ${{ github.ref_name }}-md2zhihu

  • target_platform:

    The platform that the converted markdown should be compatible with the specified platform. the currently supported platforms are zhihu, wechat, weibo, simple. simple converts almost everything to images and removes most text styles. E.g. inline code block is converted to normal text.

    required: False default: zhihu

  • image:

    The docker image that runs md2zhihu. The action pulls it from its registry before each run. Set it to a release, such as ghcr.io/drmingdrmer/md2zhihu:v0.22, to keep using that release.

    required: False default: ghcr.io/drmingdrmer/md2zhihu:latest

2. Use it on your laptop

System requirements

macOS

# For rendering table to html, and graphviz to images
brew install pandoc graphviz node
npm install -g @mermaid-js/mermaid-cli mathjax-full@3.2.2
pip install md2zhihu
# For rendering mermaid, code blocks, tables and math to images
playwright install chromium

Basic usage:

In a git working dir that contains markdowns to convert:

md2zhihu your_great_work.md -r .

This command converts your_great_work.md to _md2/your_great_work.md. And the assets it references are uploaded to the git repo found in current dir.

Use another git to store assets:

md2zhihu your_great_work.md -r git@github.com:drmingdrmer/md2test.git -b test

And you need write access on the git repo otherwise the assets can not be uploaded.

Other options: md2zhihu --help

Trouble shoot

  • command not found: md2zhihu

    Try:

    • pip install --verbose md2zhihu Confirm that install done successfully.
    • which md2zhihu Confirm that the binary can be found. The path it prints is the install path.
    • echo $PATH Confirm that this path is included in PATH.
  • Github workflow complains about permission: remote: Permission to ... denied to github-actions

    remote: Permission to <your_repo>.git denied to github-actions[bot].
    fatal: unable to access 'https://github.com/<your_name>/<your_repo>.git/': The requested URL returned error: 403
    

    Try:

    • Navigate into the repo settings
    • Click the "Action" dropdown
    • Then "General"
    • Scroll down a little till you see "Workflow permissions"
    • It is probably on "Read repository contents and packages permissions"
    • Click "Read and write permissions"
    • Scroll down and save.

3. Use it with Docker

The image ghcr.io/drmingdrmer/md2zhihu contains md2zhihu and all the tools it needs. Run it in the dir that contains the markdown:

docker run --rm -v "${PWD}:/work" ghcr.io/drmingdrmer/md2zhihu md2zhihu your_great_work.md

This command converts your_great_work.md to _md2/your_great_work.md, and saves the images in _md2/your_great_work/ without uploading them.

To upload the images to a git repo:

docker run --rm -v "${PWD}:/work" \
    -e GITHUB_USERNAME=<user> -e GITHUB_TOKEN=<token> \
    ghcr.io/drmingdrmer/md2zhihu \
    md2zhihu your_great_work.md -r https://github.com/<owner>/<repo>.git -b <branch>

<token> is a personal access token that can write to <owner>/<repo>. The container has no SSH key, so -r must be an https:// URL. For gitee.com, put the token in the URL instead: -r https://<user>:<token>@gitee.com/<owner>/<repo>.git -b <branch>.

Features

  • Transform latex to image:

    E.g. $$ ||X{\vec {\beta }}-Y||^{2} $$ is converted to

  • Transform table to HTML.

  • Upload images, and the local files that links refer to, such as [paper](paper.pdf), to specified git repo.

  • Transform mermaid code block to image:

    graph LR
        A[Hard edge] -->|Link text| B(Round edge)
        B --> C{Decision}
        C -->|One| D[Result one]
        C -->|Two| E[Result two]
    

    is converted to:

  • Transform graphviz code block to image:

    digraph R {
        node [shape=plaintext]
        rankdir=LR
        X0X0 [ label="0-0"]
        X0X0 -> X1X0 [ color="#aaaadd"]
        X0X0 -> X2X3 [ color="#aaaadd"]
    }
    

    is converted to:

  • Generate link list:

    original converted imported

Limitation

  • zhihu.com does not support markdown syntax inside a table cell. These in-table-cell content are transformed into plain text.

  • md2zhihu can not deal with jekyll/github page tags. E.g. {% octicon mark-github height:24 %}.

Metadata

Release files for md2zhihu 0.22

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for md2zhihu 0.22
File Size Uploaded Provenance Actions
md2zhihu-0.22.tar.gz 97.2 kB Without provenance Details for md2zhihu-0.22.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for md2zhihu 0.22
File Interpreter ABI Platform Actions
md2zhihu-0.22-py3-none-any.whl Python 3 none any Details for md2zhihu-0.22-py3-none-any.whl

Total release size: 155.7 kB

Release files / md2zhihu-0.22.tar.gz

Download URL md2zhihu-0.22.tar.gz
Size 97.2 kB
Tags Source
SHA-256 checksum
How to use checksums
ee5987697fe561bb5a57bbdd227098b4c6264e917a962f7970aef25e9d5c3d82
BLAKE2b-256 checksum
How to use checksums
72e8d8a0f8e35b1ac93f4358405a431738f49a643679304400f45c70f393aad7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / md2zhihu-0.22-py3-none-any.whl

Download URL md2zhihu-0.22-py3-none-any.whl
Size 58.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2110c90614dc1cb98415a45ec5a79dec15ee1985d00a23af350524fec6adec69
BLAKE2b-256 checksum
How to use checksums
61fd2bd3be9dcb18c4a179100c481761e03f92b49ac646bc1e1b948b2f006e0d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Security for md2zhihu 0.22

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.22 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page