How enveloppe/obsidian-enveloppe works
Based on our analysis of the file tree and README, we’re dealing with an Obsidian plugin that serves as a GitHub-based vault publisher. In short, this project converts your Obsidian vault—transforming wikilinks, handling Dataview queries, cleaning up the repository, and more—so that your notes can be published on a GitHub repository (using templates like Jekyll, Mkdocs, Hugo, etc.).
Main Components
a. Commands Module – (located in src/commands)
• Contains multiple command scripts (upload, refresh, purge, etc.) that act as the interface between user input and the plugin’s operations.
b. Conversion Engine – (located in src/conversion)
• Implements the conversion logic including:
– Converting Obsidian wikilinks to Markdown links.
– Handling Dataview queries, inline syntax, and link updates.
– Managing file paths and link repair.
c. GitHub Communication Module – (located in src/GitHub)
• Manages API interactions (branch creation, file upload, branch merging, conflict handling, etc.).
d. Configuration & Settings – (scattered in src/settings, manifest.json, etc.)
• Governs user settings, initial configuration, and integration options (like GitHub token management).
e. Internationalization Support – (in src/i18n)
• Manages language and localization files.
f. Utility & Type Definitions – (src/utils and src/@types)
• Contains helper functions for validation, logging, and shared types/interfaces.
Relationships and Data Flows
• User actions in Obsidian trigger specific commands which are handled by the Commands Module.
• Commands invoke the Conversion Engine to process markdown (translating wikilinks to standard Markdown, fixing folder notes etc.).
• Once conversion is completed, the GitHub Module takes over to push the content to the appropriate branch and repository.
• Settings and configuration data (e.g., repository details, GitHub token) are referenced throughout the process.
• Utility modules support logging, error validation, and data manipulation across these operations.
Architectural Patterns and Design Principles
• Modular Separation – Each major responsibility (commands, conversion, GitHub interaction, configuration) is encapsulated in its own set of directories.
• Clear Separation of Concerns – UI/Command handling is separated from data conversion and external communication.
• Extensibility – The plugin is designed so that new commands or conversion routines can be added without significant restructuring.
• Emphasis on configuration – Settings and internationalization are independently handled to keep the core logic clean.
Incorporate Relevant Technologies
• Written in TypeScript, using modern JavaScript features.
• Uses Node tooling (esbuild, Dockerfile for containerization, etc.) and GitHub workflows for CI/CD.
• Utilizes external libraries for internationalization (i18next) and might integrate with Obsidian’s API conventions.