article-sync

README

Article Sync

Manage your articles using git. Synchronize markdown files from a git repository to dev.to.

Directory Structure

This relies on having a directory structure where each article/post consists of a directory with article.md and article.json:

articles/
└── test-article
    ├── article.json
    └── article.md

• article.md: this is the markdown contents of the post
• article.json: this contains some extra details about the post like the title and ID:

  {
      "title": "My New Article",
      "description": "this article is a test"
  }
  

Once an article is posted, the ID and slug are saved to the article.json file:

{
    "id": 1234,
    "slug": "my-new-article-1234",
    "title": "My New Article",
    "description": "this article is a test"
}

GitHub Action Usage

When opening a PR, comment a summary of changes

name: Synchronization summary
on:
  pull_request:
    branches:
      - main
jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: calvinmclean/article-sync@v1.2.0
        with:
          type: summary
          api_key: ${{ secrets.DEV_TO_API_KEY }}

After pushing to main, synchronize with dev.to and make a commit with new IDs if articles are created

name: Synchronize and commit
on:
  push:
    branches:
      - main
jobs:
  commit_file:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: calvinmclean/article-sync@v1.2.0
        with:
          type: synchronize
          api_key: ${{ secrets.DEV_TO_API_KEY }}

This works declaratively by parsing each article and:

• If it does not have an ID, create a new article and save ID
• If it does have an ID:
  • Compare to existing contents fetched by ID
  • Update if changed, otherwise leave alone

Import Existing Articles

Simply run the CLI with --init flag to initialize a directory structure from existing articles. Directory names use the article slug, but can be renamed without affecting the program.

go run -mod=mod github.com/calvinmclean/article-sync@latest \
  --api-key $API_KEY \
  --init

Roadmap

• Allow naming files other than article.md or article.json