{"id":35717599,"url":"https://github.com/ecxod/mod_mermaid","last_synced_at":"2026-01-06T06:04:38.776Z","repository":{"id":288682488,"uuid":"968868899","full_name":"ecxod/mod_mermaid","owner":"ecxod","description":"A lightweight Apache module for rendering Mermaid diagram files (.mmd) as SVG directly in the browser, without caching or additional tools.","archived":false,"fork":false,"pushed_at":"2025-04-19T03:56:59.000Z","size":26,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-19T09:54:39.124Z","etag":null,"topics":["apache2","apache24","mermaid","mermaid-cli"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ecxod.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-04-18T22:14:24.000Z","updated_at":"2025-04-19T06:56:45.000Z","dependencies_parsed_at":"2025-04-20T13:03:08.060Z","dependency_job_id":null,"html_url":"https://github.com/ecxod/mod_mermaid","commit_stats":null,"previous_names":["ecxod/mod_mermaid"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/ecxod/mod_mermaid","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecxod%2Fmod_mermaid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecxod%2Fmod_mermaid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecxod%2Fmod_mermaid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecxod%2Fmod_mermaid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ecxod","download_url":"https://codeload.github.com/ecxod/mod_mermaid/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ecxod%2Fmod_mermaid/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28222603,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2026-01-06T02:00:07.049Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apache2","apache24","mermaid","mermaid-cli"],"created_at":"2026-01-06T06:03:42.307Z","updated_at":"2026-01-06T06:04:38.753Z","avatar_url":"https://github.com/ecxod.png","language":"C","readme":"# mod_mermaid\n\nAn Apache module for dynamically rendering [Mermaid](https://mermaid-js.github.io/mermaid/) diagram files (`.mmd`) as SVG directly in the browser. This module allows you to serve Mermaid diagrams without generating static HTML pages or caching SVG files, ensuring diagrams are always up-to-date and rendered on-the-fly.\n\n## Features\n- **Dynamic Rendering**: Converts `.mmd` files to SVG diagrams in real-time using the Mermaid CLI (`mmdc`).\n- **No Caching**: Always serves the latest version of your diagrams, avoiding outdated cached files.\n- **Lightweight**: Requires only Apache and the Mermaid CLI, with no additional tools or dependencies.\n- **Intranet-Friendly**: Ideal for intranet environments where users want to view `.mmd` files directly in a browser.\n- **Secure**: Uses safe execution methods (`fork`/`exec`) to prevent command injection vulnerabilities.\n\n## Prerequisites\nTo use `mod_mermaid`, you need the following installed on your system:\n- **Apache HTTP Server** (2.4 or later) with development tools (`apxs`).\n- **Mermaid CLI** (`mmdc`): Installed via npm.\n- **Chromium** (or Chrome): Required by Mermaid CLI for rendering diagrams.\n- **APR** (Apache Portable Runtime) and development headers.\n\n## Installation\n\n### Step 1: Install Dependencies\n1. **Install Apache and Development Tools**:\n   On Debian/Ubuntu:\n   ```bash\n   sudo apt update\n   sudo apt install apache2 apache2-dev\n   ```\n\n2. **Install Mermaid CLI**:\n   Install Node.js and npm, then install the Mermaid CLI globally:\n   ```bash\n   sudo apt install nodejs npm\n   npm install -g @mermaid-js/mermaid-cli\n   ```\n\n3. **Install Chromium**:\n   Install Chromium (or Chrome) and configure Puppeteer:\n   ```bash\n   sudo apt install chromium\n   export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium\n   export PUPPETEER_CACHE_DIR=/var/cache/puppeteer\n   npx puppeteer browsers install chrome-headless-shell\n   ```\n\n   Add these environment variables to Apache's configuration for persistence:\n   ```bash\n   sudo nano /etc/apache2/envvars\n   ```\n   Append:\n   ```bash\n   export PUPPETEER_EXECUTABLE_PATH=/usr/bin/chromium\n   export PUPPETEER_CACHE_DIR=/var/cache/puppeteer\n   ```\n\n### Step 2: Compile and Install the Module\n1. Clone this repository:\n   ```bash\n   git clone https://github.com/ecxod/mod_mermaid.git\n   cd mod_mermaid\n   ```\n\n2. Compile and install the module using `apxs`:\n   ```bash\n   apxs -c -i mod_mermaid.c\n   ```\n\n3. Enable the module in Apache:\n   ```bash\n   sudo a2enmod mermaid\n   ```\n\n4. Restart Apache to apply changes:\n   ```bash\n   sudo service apache2 restart\n   ```\n\n### Step 3: Configure Apache\nTo enable `mod_mermaid` for `.mmd` files, add the following to your Apache configuration (e.g., `/etc/apache2/sites-available/000-default.conf` or a dedicated configuration file like `/etc/apache2/mods-available/mermaid.conf`):\n\n```apache\n\u003cFilesMatch \"\\.mmd$\"\u003e\n    SetHandler mermaid\n\u003c/FilesMatch\u003e\n```\n\nIf you created a separate configuration file, enable it:\n```bash\nsudo a2enconf mermaid\nsudo service apache2 restart\n```\n\nEnsure that the directory containing your `.mmd` files is accessible to the Apache user (`www-data` on Debian/Ubuntu):\n```bash\nsudo chmod -R o+r /path/to/your/mmd/files\nsudo chown -R www-data:www-data /var/cache/puppeteer\nsudo chmod -R u+rw /var/cache/puppeteer\n```\n\n## Installing via Debian Package\n1. Download the latest `.deb` package from the [Releases](https://github.com/ecxod/mod_mermaid/releases) page.\n2. Install the package:\n   ```bash\n   sudo dpkg -i mod-mermaid_1.0-1_amd64.deb\n   sudo apt install -f\n\n## Usage\n\n1. Place your Mermaid diagram files (`.mmd`) in a directory served by Apache (e.g., `/var/www/html/diagrams/`).\n2. Access the `.mmd` file via your browser, e.g., `http://your-server/diagrams/FlowChart.mmd`.\n3. The module will render the diagram as an SVG embedded in a simple HTML page.\n\nExample `.mmd` file (`FlowChart.mmd`):\n```mermaid\ngraph TD\n    A[Start] --\u003e B[Process]\n    B --\u003e C[End]\n```\n## JavaScript-Free Diagram Rendering for Console Browsers\n\n`mod_mermaid` is perfect for serving Mermaid diagrams without relying on client-side JavaScript, making it ideal for lightweight or text-based browsers like `w3m`, `lynx`, or other minimalistic clients. By rendering `.mmd` files as SVGs server-side, the module ensures that diagrams are accessible in environments where JavaScript is disabled or unavailable, such as:\n\n- **Console Browsers**: Tools like `w3m` (with SVG support) can display diagrams directly in the terminal.\n- **Low-Resource Devices**: Embedded systems or legacy clients benefit from pre-rendered SVGs.\n- **Security-Conscious Environments**: Avoid JavaScript to reduce attack surfaces in sensitive intranet setups.\n\n### How It Works\n1. Place your `.mmd` files in an Apache-served directory.\n2. Configure Apache to use the `mermaid` handler for `.mmd` files (see [Installation](#installation)).\n3. Access the diagram via a URL (e.g., `http://your-server/diagrams/FlowChart.mmd`) in a console browser like `w3m`:\n   ```bash\n   w3m http://your-server/diagrams/FlowChart.mmd\n   ```\n4. The module converts the `.mmd` file to an SVG embedded in a simple HTML page, which is rendered without any client-side JavaScript.\n\n## Benefits\n\n- No JavaScript Overhead: Diagrams are fully rendered on the server, ensuring compatibility with JavaScript-free clients.\n- Lightweight: Minimal HTML and SVG output keeps pages fast and accessible.\n- Broad Compatibility: Works with any browser or client that supports basic HTML and SVG, including terminal-based tools.\n\n## Notes\n\n- Ensure your console browser (e.g., w3m) is compiled with SVG support for optimal rendering. Check your browser's documentation for details.\n- For the best experience, keep .mmd diagrams simple, as complex SVGs may challenge some text-based browsers.\n\nThis feature makes mod_mermaid a versatile tool for delivering dynamic diagrams in constrained or security-focused environments.\n\n\n## Troubleshooting\n- **Check Apache Logs**: If diagrams fail to render, check the Apache error logs for details:\n  ```bash\n  tail -f /var/log/apache2/error.log\n  ```\n- **Verify Mermaid CLI**: Test `mmdc` manually as the Apache user:\n  ```bash\n  sudo -u www-data /usr/local/bin/mmdc -i /path/to/diagram.mmd -o /tmp/test.svg\n  ```\n- **Permissions**: Ensure the Apache user (`www-data`) has read access to `.mmd` files and write access to `/var/cache/puppeteer`.\n- **Environment Variables**: Confirm that `PUPPETEER_EXECUTABLE_PATH` and `PUPPETEER_CACHE_DIR` are set in `/etc/apache2/envvars`.\n\n## Contributing\nContributions are welcome! Please submit a pull request or open an issue on GitHub to suggest improvements or report bugs.\n\n## License\nThis project is licensed under the [MIT License](LICENSE).\n\n## Acknowledgments\n- Built with the [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli) for diagram rendering.\n- Inspired by the need for a simple, dynamic way to view Mermaid diagrams in an intranet environment.\n\n---\n\nHappy diagramming! 🚀","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecxod%2Fmod_mermaid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fecxod%2Fmod_mermaid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fecxod%2Fmod_mermaid/lists"}