doc: describe action-usage and local usage

drmingdrmer · Mar 5, 2021 · 4ebeead · 4ebeead
1 parent 394ac14
commit 4ebeead
Show file tree

Hide file tree

Showing 2 changed files with 84 additions and 108 deletions.
diff --git a/README.md b/README.md
@@ -1,135 +1,83 @@
 # md2zhihu
 
-将markdown转换成 知乎 兼容的 markdown 格式
+Converts markdown to a single-file version that has no local asset dependency
+and can be imported into zhihu.com with just one click.
 
-|       | md源文件              | 导入知乎的效果          |
-|:--    | :-:                   | :-:                     |
-|使用前 | ![](assets/md.png)    |  ![](assets/before.png) |
-|转换后 | ![](assets/built.png) |  ![](assets/after.png)  |
+|           | md                    | imported               |
+| :--       | :-:                   | :-:                    |
+| original  | ![](assets/md.png)    | ![](assets/before.png) |
+| converted | ![](assets/built.png) | ![](assets/after.png)  |
 
-## Install
+## Usage
+
+Add action definition into the git repo you have markdowns to convert:
+`.github/workflows/md2zhihu.yml`:
+
+To create and add `GH_TOKEN`, see: [add-token](add-token.md)
+
+```yaml
+name: md2zhihu
+on: [push]
+jobs:
+  md2zhihu:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    - uses: drmingdrmer/[email protected]
+      env:
+        GITHUB_USERNAME: ${{ github.repository_owner }}
+        GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
+      with:
+        pattern: >
+            _posts/*.md
+            _posts/*.markdown
+```
+
+The next push github converts markdowns in `_posts/` and stores converted
+version in branch `_md2zhihu/md`.
+
+E.g., the single-file version of all of my blog posts:
+https://github.com/drmingdrmer/drmingdrmer.github.io/tree/_md2zhihu/md/_md2zhihu
+
+To retrieve the converted markdowns, merge branch `_md2zhihu/md`,
+or access the branch on the web:
+https://github.com/drmingdrmer/drmingdrmer.github.io/blob/_md2zhihu/md/_md2zhihu/dict-cmp.md
+
+
+## Use it Locally
 
 System requirement: MaxOS
 
 ```sh
 # For rendering table to html
 brew install pandoc imagemagick node
 npm install -g @mermaid-js/mermaid-cli
-```
-
-```sh
 pip install md2zhihu
 ```
 
-## Usage
-
 ```sh
 md2zhihu your_great_work.md
 ```
 
-这个命令将markdown 转换成 知乎 文章编辑器可直接导入的格式, 存储到 `_md2/your_great_work/your_great_work.md`, 然后将图片等资源上传到**当前目录所在的git**的`_md2zhihu`分支. 转换后的markdown文档不依赖任何本地的图片文件或其他文件.
-
-- `-d` 指定输出目录, 默认为`./_md2/`; 所有文章都会保存在这个目录中,
-    名为`<article_name>` 的md转换之后保存在`_md2/zhihu/<article_name>/` 目录中,
-    包括一个名为`<article_name>.md` 的md文件以及所有使用的图片等在同一个目录下.
-
-    转换后所有输出内容将会push到`-r`指定的git repo中或当前目录下的git的repo中.
-
-- `-r` 指定用于存储图片等资源的git repo url和上传的分支名; 要求是对这个repo有push权限.
-
-    例如要将图片等上传到`github.com/openacid/foo`项目中的`bar`分支:
-    ```
-    md2zhihu great.md -r https://github.com/openacid/foo.git@bar
-    ```
-
-    默认使用当前目录下的git配置, (作者假设用户用git来保存自己的工作:DDD),
-    如果没有指定分支名, md2zhihu 将建立一个`_md2zhihu_{cwd_tail}_{md5(cwd)[:8]}`的分支来保存所有图片.
-
-## 使用 github-action 远程转换, 适合 Windows 用户
-
-md2zhihu 不支持windows, 可以通过github-action来实现远程转换:
-
--   首先将要转换的 markdown 全部放在一个 github repo 中, 完成配置后, 每次 push 之后 github-action 将自动构建,
-    例如 我自己的博客中的文章都在这个repo中: https://github.com/drmingdrmer/drmingdrmer.github.io
-
--   生成 github token, 以授权github action可以将转换的文档 push 回 repo:
-    通过以下链接创建:
-    https://github.com/settings/tokens/new
-
-    步骤可参考:
-    https://docs.github.com/cn/github/authenticating-to-github/creating-a-personal-access-token
-
-    创建后应该在以下页面看到刚创建的token:
-    https://github.com/settings/tokens
-
-    ![](assets/create-token.png)
-
--   将上面生成的token 添加到存储文章的 repo, 名为 `GH_TOKEN`,
-    接着让 github-action 使用这个 token 来 push 代码:
-    在 repo 主页, 通过菜单 setting-Secrets-New repository secret 进入添加token页面.
-
-    例如我博客repo的添加token的在:
-    https://github.com/drmingdrmer/drmingdrmer.github.io/settings/secrets/actions
-
-    添加后效果如下:
-
-    ![](assets/add-token.png)
-
--   在文章 repo 中创建 action 描述文件, 定义一个 github-action,
-    为每次 push 进行转换:
-    `.github/workflows/md2zhihu.yml`, 内容为:
-
-    ```yaml
-    name: md2zhihu
-    on: [push]
-    jobs:
-      md2zhihu:
-        runs-on: ubuntu-latest
-        steps:
-        - uses: actions/checkout@v2
-        - uses: drmingdrmer/[email protected]
-          env:
-            GITHUB_USERNAME: ${{ github.repository_owner }}
-            GITHUB_TOKEN: ${{ secrets.GH_TOKEN }}
-          with:
-            pattern: >
-                _posts/*.md
-                _posts/*.markdown
-    ```
-    然后将配置文件 commit 到 repo 中:
-    `git add .github && git commit -m 'action: md2zhihu'`
-
-    用以上配置, 在下一次push时, github action 将目录 `_posts/` 中所有的md文件进行转换,
-    并保存到`_md2zhihu/md` 分支中.
-
-    例如我的博客中文章装换后在:
-    https://github.com/drmingdrmer/drmingdrmer.github.io/tree/_md2zhihu/md/_md2zhihu
-
--   要使用转换后的文档, 可以直接 merge 这个`_md2zhihu/md`分支
-
-    或直接从github repo 中访问, 例如:
-    https://github.com/drmingdrmer/drmingdrmer.github.io/blob/_md2zhihu/md/_md2zhihu/dict-cmp.md
-
+This command convert `your_great_work.md` to
+`_md2/zhihu/your_great_work/your_great_work.md`.
 
 ## Features
 
-- 公式转换:
+- Transform latex to image:
 
-  例如 ` $$ ||X{\vec {\beta }}-Y||^{2} $$ `
+  E.g. ` $$ ||X{\vec {\beta }}-Y||^{2} $$ ` is converted to 
   ![](https://www.zhihu.com/equation?tex=%7C%7CX%7B%5Cvec%20%7B%5Cbeta%20%7D%7D-Y%7C%7C%5E%7B2%7D)
-  转换成可以直接被知乎使用的tex渲染引擎的引用:
 
   ```
   <img src="https://www.zhihu.com/equation?tex=||X{\vec {\beta }}-Y||^{2}\\" ...>
   ```
 
-- 自动识别block的公式和inline的公式.
-
-- 表格: 将markdown表格转换成html 以便支持知乎直接导入.
+- Transform table to html.
 
-- 图片: md2zhihu 将图片上传到github, 并将markdown中的图片引用做替换.
+- Upload images.
 
-- mermaid: 将mermaid语法渲染成图片, 并上传. 例如:
+- Transform mermaid code block to image:
 
     ```mermaid
     graph LR
@@ -139,19 +87,20 @@ md2zhihu 不支持windows, 可以通过github-action来实现远程转换:
         C -->|Two| E[Result two]
     ```
 
-    转换成:
+    is converted to:
 
     ![](assets/mermaid.jpg)
 
--   链接列表: 将 markdown 的 reference-style link 转成链接列表:
+-   Generate link list::
 
-    | 源文件 | 转换后 | 导入后 |
+    | original | converted | imported |
     | :-: | :-: | :-: |
     | ![](assets/ref-list/src.png) | ![](assets/ref-list/dst.png) | ![](assets/ref-list/imported.png) |
 
 
-
 ## Limitation
 
-- 知乎的表格不支持table cell 中的markdown格式, 例如表格中的超链接, 无法渲染, 会被知乎转成纯文本.
-- md2zhihu 无法处理jekyll/github page的功能标签例如 `{% octicon mark-github height:24 %}`. 这部分文本目前需要导入后手动删除或修改.
+- zhihu.com does not support markdown syntax inside a table cell.
+  These in-table-cell content are transformed to plain text.
+
+- md2zhihu can not deal with jekyll/github page tags. E.g. `{% octicon mark-github height:24 %}`.
diff --git a/add-token.md b/add-token.md
@@ -0,0 +1,27 @@
+## Generate token
+
+A token is required to let md2zhihu to push converted markdowns back to the
+repo. To generate a token, follow the link:
+https://github.com/settings/tokens/new
+
+And follow steps described here:
+https://docs.github.com/cn/github/authenticating-to-github/creating-a-personal-access-token
+
+A generated token can been seen here:
+https://github.com/settings/tokens
+
+![](assets/create-token.png)
+
+## Add token to repo
+
+Name the generated token `GH_TOKEN` and add it to the repo that contains
+original markdowns, so that md2zhihu is able to push converted markdown back to
+this repo:
+
+On the home page of the repo, follow the menu:
+setting-Secrets-New repository secret.
+
+E.g., the secret token for my blog:
+https://github.com/drmingdrmer/drmingdrmer.github.io/settings/secrets/actions
+
+![](assets/add-token.png)