new-feature: local mode; support using git-remote

- changes of CLI:

    - `--asset-dir` is removed.

    - `--output-dir`: the root git dir to push to remote, which contains
      converted assets. A git repo will be initialized in this dir.

    - `--asset-output-dir`: the dir to store assets. Most cases you do
      not need to set this path.

- changes of github-action:

    - `md_branch` is removed. Now it always pushes to the branch it
      converts md from.

- new-feature: support specifying a remote as url of the repo that
  stores converted assets.

- new-feature: if `--repo` is not specified, it convert md locally,
  i.e., assets are linked by relative path, and nothing is pushed to
  remote.

- test: when CI, use repo md2test to test pushing.

- refactor: extract common util func from test, such as comparing md,
  comparing images.

- refactor: use feature-list to describe platform specific convertion.

- refactor: use k3git to parse git url.

.github/workflows/python-package.yml

@@ -12,34 +12,47 @@ jobs:
 
     runs-on: ubuntu-latest
     strategy:
+      # parallel running result in conflict when git-push to a same branch
+      max-parallel: 1
       matrix:
         python-version: [3.6, 3.7, 3.8]
 
     steps:
     - uses: actions/checkout@v2
+
     - name: Set up Python ${{ matrix.python-version }}
       uses: actions/setup-python@v2
       with:
         python-version: ${{ matrix.python-version }}
+
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip
         pip install flake8 pytest
         if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
         if [ -f test-requirements.txt ]; then pip install -r test-requirements.txt; fi
+
     - name: Install npm dependencies
       run: |
         if [ -f package.json ]; then npm install; fi
+
     - name: Install apt dependencies
       run: |
         if [ -f packages.txt ]; then cat packages.txt | xargs sudo apt-get install; fi
+
     - name: Lint with flake8
       run: |
         # stop the build if there are Python syntax errors or undefined names
         flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics
         # exit-zero treats all errors as warnings. The GitHub editor is 127 chars wide
         flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics
+
     - name: Test with pytest
+      env:
+        # pass in committer and token to access a test repo:
+        # https://github.com/drmingdrmer/md2test
+        MD2TEST_USERNAME: ${{ github.repository_owner }}
+        MD2TEST_TOKEN: ${{ secrets.MD2TEST_TOKEN }}
       run: |
         pip install setuptools wheel twine
         cp setup.py ..

README-cn.md

@@ -59,6 +59,8 @@ md2zhihu your_great_work.md
 
 md2zhihu 不支持windows, 可以通过github-action来实现远程转换:
 
+Action: https://github.com/marketplace/actions/md2zhihu
+
 -   首先将要转换的 markdown 全部放在一个 github repo 中, 完成配置后, 每次 push 之后 github-action 将自动构建,
     例如 我自己的博客中的文章都在这个repo中: https://github.com/drmingdrmer/drmingdrmer.github.io
 
@@ -87,7 +89,7 @@ md2zhihu 不支持windows, 可以通过github-action来实现远程转换:
     `git add .github && git commit -m 'action: md2zhihu'`
 
     用以上配置, 在下一次push时, github action 将目录 `_posts/` 中所有的md文件进行转换,
-    并保存到`_md2zhihu/md` 分支中.
+    并在当前分支创建一个新提交点, 其中目录`_md2zhihu` 保存了所有转换后的md文件.
 
     例如我的博客中文章装换后在:
     https://github.com/drmingdrmer/drmingdrmer.github.io/tree/_md2zhihu/md/_md2zhihu

README.md

@@ -10,6 +10,8 @@ and can be imported into zhihu.com with just one click.
 
 ## Usage
 
+Action: https://github.com/marketplace/actions/md2zhihu
+
 Add action definition into the git repo you have markdowns to convert:
 `.github/workflows/md2zhihu.yml`:
 
@@ -31,8 +33,8 @@ jobs:
             _posts/*.markdown
 ```
 
-The next push github converts markdowns in `_posts/` and stores converted
-version in branch `_md2zhihu/md`.
+The next push github converts markdowns in `_posts/` and creates a new commit
+that contains the converted markdowns in folder `_md2zhihu`.
 
 E.g., the single-file version of all of my blog posts:
 https://github.com/drmingdrmer/drmingdrmer.github.io/tree/_md2zhihu/md/_md2zhihu

__init__.py

@@ -10,4 +10,5 @@
 from . import mistune
 from .md2zhihu import main
 from .md2zhihu import AssetRepo
+from .md2zhihu import LocalRepo
 from .md2zhihu import Config

action-doc.md

@@ -7,21 +7,14 @@
 
 -   `output_dir`:
 
-    dir to store converted markdown
+    dir to store converted markdown.
 
     **required**: True
     **default**: `_md2zhihu`
 
--   `md_branch`:
-
-    The branch name to push converted markdown to. A build overrides previous built branch. If you want to persist the built markdowns, merge this branch.
-
-    **required**: True
-    **default**: `_md2zhihu/md`
-
 -   `asset_branch`:
 
-    The branch name in which assets are stored.
+    The branch in which assets are stored. This branch must NOT be removed otherwise the assets will not be accessed.
 
     **required**: True
     **default**: `_md2zhihu/asset`

action.yml

@@ -1,32 +1,27 @@
 name: 'md2zhihu'
 description: >
-  Convert markdown to a single-file by uploading all its local assets.
+  Convert markdown to a single-file by uploading local assets.
+
 branding:
   icon: upload-cloud
   color: green
+
 inputs:
   pattern:
     description: 'file pattern to convert'
     required: true
     default: '**/*.md'
 
   output_dir:
-    description: 'dir to store converted markdown'
-    required: true
-    default: '_md2zhihu'
-
-  md_branch:
     description: >
-      The branch name to push converted markdown to.
-      A build overrides previous built branch.
-      If you want to persist the built markdowns,
-      merge this branch.
+      dir to store converted markdown.
     required: true
-    default: '_md2zhihu/md'
+    default: '_md2zhihu'
 
   asset_branch:
     description: >
-      The branch name in which assets are stored.
+      The branch in which assets are stored.
+      This branch must NOT be removed otherwise the assets will not be accessed.
     required: true
     default: '_md2zhihu/asset'
 
@@ -66,8 +61,7 @@ runs:
           --repo https://github.com/${{ github.repository }}.git@${{ inputs.asset_branch }} \
           --code-width 600 \
           --platform ${{ inputs.target_platform }} \
-          --asset-dir _md2zhihu \
-          --md-output ${{ inputs.output_dir }} \
+          --md-output ${{ inputs.output_dir }}/ \
           ${{ inputs.pattern }}
 
         git add ${{ inputs.output_dir }}
@@ -77,7 +71,7 @@ runs:
           -c "[email protected]" \
           commit -m "md2zhihu built"
 
-        git push -f origin HEAD:refs/heads/${{ inputs.md_branch }}
+        git push -f origin HEAD:${{ github.ref }}
 
-        echo "::set-output name=converted_branch::https://github.com/${{ github.repository }}/tree/${{ inputs.md_branch }}"
+        echo "::set-output name=converted_branch::https://github.com/${{ github.repository }}/tree/${{ github.ref }}"
       shell: bash