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.

md2zhihu on Marketplace

	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. See: md2zhihu on Marketplace

Note: use asset_repo to specify a gitee.com repo so that zhihu.com load images from it when importing.

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
    steps:
    - uses: actions/checkout@v2
    - uses: drmingdrmer/md2zhihu@main
      env:
        GITHUB_USERNAME: ${{ github.repository_owner }}
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      with:
        pattern: >
            _posts/*.md
            _posts/*.markdown

        asset_repo: https://${{ secrets.GITEE_PUSH_DRDRXP_REPO }}@gitee.com/drdrxp/bed.git

The conversion will be triggered on the next push:

It will convert markdown files in the _posts/ directory and save them in the _md2zhihu directory. A new branch master-md2zhihu containing these outputs will be created:

Branch master:

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

Branch master-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 master-md2zhihu.
• Or access this branch directly on the web: single-file example

Action Options for md2zhihu

• pattern:

  File pattern to convert

  required: True default: **/*.md

• output_dir:

  Directory to store converted markdown

  required: True 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/drdrxp/bed.git
     

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

• asset_branch:

  The branch name in which assets are stored.

  required: True 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: True 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: True 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.18, to keep using that release.

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

2. Use it on your laptop

System requirements

MaxOS

# 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 assests 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: e.g.: /Users/drdrxp/xp/py3virtual/p38/bin/md2zhihu.
  • echo $PATH Confirmat that the install path is included in PATH: ...:/Users/drdrxp/xp/py3virtual/p38/bin:...

• 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 %}.