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
# Convert: write the converted markdown and its images into _md2zhihu.
- uses: drmingdrmer/md2zhihu@v0.23
# Publish: push the workspace with _md2zhihu to the branch <branch>-md2zhihu.
- run: |
git add _md2zhihu
git -c user.name=md2zhihu -c user.email=noreply@localhost commit --allow-empty -m "md2zhihu built"
git push -f origin HEAD:refs/heads/${{ github.ref_name }}-md2zhihu
A push runs this workflow. The action converts each markdown file and writes
the result into _md2zhihu in the workspace, with the images of post.md in
_md2zhihu/post/. The action pushes nothing. The last step publishes
_md2zhihu: it pushes the workspace to a branch named after the branch that
was pushed, with -md2zhihu added. A push to main creates main-md2zhihu.
That step is the only one that writes to the repo, so it is the only reason
for permissions: contents: write.
Branch main:
▾ _posts/
2013-01-31-jobq.markdown
2013-01-31-resource.markdown
...
Branch main-md2zhihu:
▾ _posts/
2013-01-31-jobq.markdown
2013-01-31-resource.markdown
...
▾ _md2zhihu/
jobq.md
jobq/
resource.md
resource/
...
The converted markdown refers to each image by its URL on that branch, through
jsDelivr, such as
https://cdn.jsdelivr.net/gh/<owner>/<repo>@main-md2zhihu/_md2zhihu/jobq/<hash>-a.png.
zhihu.com loads an image only from a public URL, so the images show once the
last step has pushed the branch. The input asset_url_prefix sets this URL. If
you publish _md2zhihu elsewhere, such as to another repo, set it to the
public URL of _md2zhihu there. To keep relative image URLs, set it to "".
There are two ways to get the converted markdown files:
git fetchandgit mergethe branchmain-md2zhihu.- Or access this branch directly on the web: single-file example
The action of 0.22 and earlier pushed the images and the converted markdown
itself, to two branches. To keep that, stay on drmingdrmer/md2zhihu@v0.22.
Action Options for md2zhihu
-
pattern:file pattern to convert
required: False default:
**/*.md -
output_dir:dir to store converted markdown.
required: False default:
_md2zhihu -
asset_url_prefix:The public URL of
output_dironce a later step of the workflow publishes it. md2zhihu puts it before each relative URL of the converted markdown, such aspost/<hash>-a.pngof an image ofpost.md, so that a platform such as zhihu.com loads the image from there. The action pushes nothing, so the URL works only after the workflow publishesoutput_dirat that place.The default is the URL that jsDelivr serves
_md2zhihu/at, on the branch<branch>-md2zhihuof this repo, which the example workflow in README.md pushes. Change it together withoutput_dir, or with the branch that the workflow pushes.A relative link to another file, such as
../other.md, also gets the prefix. Set it to "" to keep every relative URL as it is.required: False default:
https://cdn.jsdelivr.net/gh/${{ github.repository }}@${{ github.ref_name }}-md2zhihu/_md2zhihu/ -
target_platform:The platform that the converted markdown should be compatible to.
Currently supported platforms are zhihu, wechat, weibo, simple.
simpleconverts 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.23, to keep using that release. An image of 0.22 or earlier can not run this action. To keep the push of 0.22, usedrmingdrmer/md2zhihu@v0.22.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:
md2zhihu your_great_work.md
This command converts your_great_work.md to _md2/your_great_work.md, and
writes its images into _md2/your_great_work/. The converted markdown refers
to each image by a relative URL, such as your_great_work/<hash>-a.png.
md2zhihu pushes nothing: publishing _md2 is up to you.
Refer to the images by a public URL:
zhihu.com and the other platforms load an image only from a public URL. Publish
_md2 somewhere public, such as by pushing it to the branch md2 of a GitHub
repo, and give md2zhihu the URL that _md2 gets there:
md2zhihu your_great_work.md \
--rewrite-if '^your_great_work/' '^' 'https://cdn.jsdelivr.net/gh/<owner>/<repo>@md2/'
The images of your_great_work.md then have URLs such as
https://cdn.jsdelivr.net/gh/<owner>/<repo>@md2/your_great_work/<hash>-a.png.
The three rewrite flags change the URL destination of each link and image of the output: a stored image, a remote image, and a link to another page. They do not change any other text.
--rewrite REGEX REPLACEMENTchanges every destination withre.sub(REGEX, REPLACEMENT, url).--rewrite '^' 'https://cdn.example/'also prefixes the URL of a remote image, such ashttps://a.com/x.png.--rewrite-if SELECTOR REGEX REPLACEMENTchanges only a destination in whichre.search(SELECTOR, url)finds a match. A match alone does not change it:REGEXmust match too.--rewrite-if-not SELECTOR REGEX REPLACEMENTchanges only a destination in whichre.search(SELECTOR, url)finds no match.
The rules apply in the order of the command line, each to the URL that the rule
before it made. They see the whole URL, with its query and fragment, after
md2zhihu has stored the images. With --download, a rule sees the URL of the
downloaded copy, not the remote URL.
To prefix every relative destination, leave out the URLs with a scheme or a
host, such as https:, // and data:, the paths from the root, and the
references to a query or a fragment, such as #intro:
md2zhihu your_great_work.md \
--rewrite-if-not '^([A-Za-z][A-Za-z0-9+.-]*:|//|/|[?#]|$)' '^' 'https://cdn.jsdelivr.net/gh/<owner>/<repo>@md2/'
This rule also prefixes a relative link to another file, such as
../other-post.md, because nothing in a URL tells a stored image from another
relative link. To change only the stored images, select their folder, as
--rewrite-if '^your_great_work/' above does. That selector matches a path, so
it also matches a link to your_great_work/ that you wrote yourself.
md2zhihu 0.22 and earlier pushed _md2 with -r and -b. These flags now
exit with an error. To keep the push, use pip install md2zhihu==0.22.
Other options: md2zhihu --help
Trouble shoot
-
command not found: md2zhihu
Try:
pip install --verbose md2zhihuConfirm that install done successfully.which md2zhihuConfirm that the binary can be found. The path it prints is the install path.echo $PATHConfirm that this path is included inPATH.
-
The
git pushstep of the workflow complains about permission: remote: Permission to ... denied to github-actionsremote: 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: 403Try:
- 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/. Add the rewrite flags of
Use it on your laptop to refer to the images by
the public URL that you publish _md2 at.
Features
-
Transform latex to image:
E.g.
$$ ||X{\vec {\beta }}-Y||^{2} $$is converted to -
Transform table to HTML.
-
Copy images, and the local files that links refer to, such as
[paper](paper.pdf), into the output folder, and refer to them by relative URLs, or by the public URLs that the rewrite flags give. -
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.23
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| md2zhihu-0.23.tar.gz | 95.6 kB | Without provenance | Details for md2zhihu-0.23.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| md2zhihu-0.23-py3-none-any.whl | Python 3 | none | any | Details for md2zhihu-0.23-py3-none-any.whl |
Total release size: 153.0 kB
Release files / md2zhihu-0.23.tar.gz
| Download URL | md2zhihu-0.23.tar.gz |
|---|---|
| Size | 95.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3eab8d71c305c4b4b5553d1f3b836e752e14f80d5f16288acc9ce3eb9c2be36c
|
|
BLAKE2b-256 checksum How to use checksums |
63bbaa9519e004f02851a7a556f5d72c7087f87aed6908eba70e28a65ccafb1b
|
| 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.23-py3-none-any.whl
| Download URL | md2zhihu-0.23-py3-none-any.whl |
|---|---|
| Size | 57.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3d29e8a580ec9599d885d00e99959d367bd16287472870ccc1b2fce634ae7f97
|
|
BLAKE2b-256 checksum How to use checksums |
648d1fc339c0cd107aca4ff1d1733d44e7693fb2688ba9bf12b8a9547c185f9e
|
| 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.23
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.