Markdown Organizer Action

Automatically organize, clean, and normalize Markdown files with GitHub Actions.
This project is in very early access and still under active development.
Do not use in production until a stable release is published.

---

Overview

Markdown Organizer Action helps keep Markdown repositories clean and structured.

• Sort files into folders based on frontmatter fields such as tags, categories, or dates
• Normalize tags, fix broken internal links, and enforce consistent naming conventions
• Auto-commit changes back to your repository or run in dry-run mode to preview updates
• Designed for Obsidian vaults, static site generators like Hugo and Jekyll, and developer documentation projects

---

Checklist and Roadmap

Initial Project Setup

• Create repository under Devlander-Software
• Initialize package.json and basic project structure
• Add action.yml with inputs and outputs defined
• Set up GitHub Actions CI workflow for testing
• Add early access warning to README and repo description

Core Features (MVP)

• Parse frontmatter metadata from Markdown files
• Sort and move files into folders based on:
  • Tags
  • Categories
  • Dates
• Normalize tags (lowercase, trim spaces, merge similar tags)
• Fix broken internal links between Markdown files
• Enforce consistent line endings (LF)
• Auto-commit changes back to the repository
• Add dry-run mode for previewing changes without committing

Configuration

• Support YAML configuration file (.markdown-organizer.yml)
• Allow user-defined sort criteria and folder structure
• Enable options to toggle specific features (tags, links, sorting)
• Provide defaults for zero-config use

Testing

• Set up Jest test framework
• Write unit tests for:
  • Frontmatter parsing
  • Sorting logic
  • File operations
• Write integration tests simulating vault organization
• Add CI job to run tests on every pull request

Documentation

• Draft full README with:
  • Overview
  • Features
  • Installation instructions
  • Usage examples
  • Configuration options reference
  • Contribution guidelines
• Add badges for build status, version, license
• Create Marketplace description for GitHub Actions

Pre-Release and Publishing

• Tag first pre-release (v0.1.0-beta)
• Test Action in real repositories
• Gather community feedback for improvements
• Publish stable release (v1.0.0)
• Submit to GitHub Actions Marketplace

Future Enhancements

• Add external link checker (HTTP 404 detection)
• Support custom filename patterns and renaming rules
• Generate summary dashboards (e.g., tags overview, file index)
• Support other markup formats (e.g., reStructuredText)
• Optional GitHub PR comment summary of changes
• Dockerized version for heavy workflows

---

License

MIT License