How kovetskiy/mark works
Project Type & Purpose
• Is a command-line tool written in Go that reads markdown files (with extended metadata), converts them to HTML, and then updates (or creates) corresponding pages in a Confluence instance using its REST API.
• Its purpose is to allow documentation maintained in Git repositories to be “synced” directly to Confluence without the manual overhead of using a WYSIWYG editor.
File Tree & Identify Components
• At the root level, you see key files like main.go, auth.go, a Dockerfile, Makefile, and configuration files. These indicate a CLI tool using Go, with support for containerized builds and CI via Docker and GitHub Actions.
• Several directories indicate logical separation of functionality:
• attachment: Contains code (and tests) related to handling file attachments uploaded to Confluence.
• confluence: Houses the confluence API integration – the interface that sends HTML content and pages to Confluence.
• markdown: Manages markdown processing and conversion logic.
• metadata: Parses and extracts HTML-ish metadata headers from the markdown files.
• parser: Deals with parsing specific markdown extensions such as Confluence identifiers and tags.
• renderer: Contains logic for converting markdown constructs (such as headings, blockquotes, code blocks, images, etc.) into HTML fragments.
• macro: Implements the processing and replacement of custom macros defined in the markdown.
• includes: Likely supports inserting Go templates or other include file functionality.
• page: Contains code managing Confluence page linkage, ancestry, or related page operations.
• stdlib and vfs: Provide helper functions and virtual file system utilities, respectively.
• Supporting files for CI/CD (docker-compose.yaml, Taskfile.yml, GitHub workflows, etc.) indicate an automated build and release process.
a. Break down the system into main logical components:
• CLI Frontend & Configuration: Represents main.go, auth.go, command-line flags configuration, and overall program initialization.
• Markdown Input Module:
– Metadata & File Parsing (metadata, parser directories) to extract Confluence-specific headers.
– Markdown Processing (markdown directory) that converts the base markdown content.
• Content Renderer Module:
– Renderer: Processes individual markdown elements into HTML (renderer directory).
– Macro & Template Handling: Processes macros (macro directory) and includes (includes) to extend markdown functionality.
• Attachment Handler: Manages attachments (attachment folder) ensuring that referenced files are properly located, uploaded, and embedded on the Confluence page.
• Confluence Integration Module:
– Confluence API Adapter (confluence directory) forms the connection, wraps the REST API calls to create/update pages.
– Page Managing Logic (page directory) that organizes parent-child relationships and manages title/ancestry.
• Utility & Support Modules:
– Standard Library Extensions (stdlib)
– Virtual File System (vfs)
• CI/CD & Build Components: Dockerfile, docker-compose.yaml, Makefile, and GitHub workflows; these illustrate the automated build, testing, and deployment processes.
b. Relationships & Data Flow:
• The markdown input module will first parse file metadata and then process markdown content.
• The attachment handler works concurrently where attachment paths from the metadata are checked, uploaded, and linked with the content.
• The Confluence integration module collects the final HTML output along with metadata (page titles, parent pages, etc.) and makes REST API calls to either create new pages or update existing ones.
• Optionally, include the CI/CD pipeline as an external component feeding into build and test automation.
c. Architectural Patterns and Design Principles:
• Modularization: The directory structure clearly indicates separation of concerns (parsing, rendering, API integration, attachment handling).
• Pipeline/Data Flow Pattern: Markdown input is passed through a series of processing stages (parsing, macro substitution, rendering) before being transmitted.
• Testability: Presence of corresponding _test.go files in many components indicates the design supports unit testing.
d. Technologies, Frameworks, or Libraries:
• Go Programming Language: The primary language plus dependency management (go.mod, go.sum).
• Docker & Docker Compose: Used for containerization and building the project.
• CI and Release Pipelines: GitHub Actions (workflows/ci.yml, goreleaser.yml) and Taskfile for build automation.
• Confluence REST API integration: All protocols and REST calls are built into the project through the "confluence" package.
• Markdown processing and templating libraries (standard in Go) extended with custom renderer/macro logic.