convert-md 1.0.0__tar.gz

convert_md-1.0.0/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to convert-md are listed here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-11-13
+
+First public release.
+
+### Added
+- Right-click **Convert to** submenu on `.md` and `.markdown` files: Word, PDF, Excel (tables only),
+  PowerPoint, Web page, All formats, and "As set in the file".
+- Right-click **Convert to Markdown** on `.docx .pdf .xlsx .xls .pptx .html .htm .csv .epub .msg`.
+- **Ctrl+Alt+M** hotkey in File Explorer (needs AutoHotkey v2). It reads only the active Explorer tab
+  and splits mixed selections: Markdown files go out, other files come in.
+- "As set in the file": formats from `outputs:` front-matter or the filename (`Report.docx.pdf.md`).
+- PDF output through Microsoft Word when installed, otherwise a Pandoc PDF engine.
+- Excel output with one sheet per table, named after the heading above it; numbers, currency,
+  percentages and bracketed negatives become real numbers; header row frozen and filtered.
+- House styling with `reference.docx`, `reference.pptx` and `style.css` in the templates folder;
+  `convert-md templates` creates starter copies.
+- `convert-md setup`, `remove` and `doctor` commands; `install.ps1` and `uninstall.ps1`.
+- Existing files are never overwritten; repeat runs write `Report (1).docx`.
+- Success/problem popup, and a log at `%LOCALAPPDATA%\ConvertMd\convert-md.log`.
+
+### Security
+- Menus and hotkey run Python with `-P`, so a file named `convert_md.py` in the document's folder
+  can't be run in place of convert-md.
+- Per-user install only: registry changes are under `HKEY_CURRENT_USER`; no administrator rights.
+
+### Upgrading from a pre-release copy
+Earlier private copies were called md-convert. They ran `md_convert.py` from the project folder and
+used `install.reg`, `make_reg.py` and a hand-edited `md-convert-hotkey.ahk`. Run `install.ps1`: it
+removes the old md-convert menus, Startup shortcut and running hotkey and installs convert-md in their
+place. The old files are no longer used and can be deleted, as can `%LOCALAPPDATA%\MdConvert`
+(it only holds the old log).
+
+[Unreleased]: https://github.com/W3i-io/convert-md/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/W3i-io/convert-md/releases/tag/v1.0.0

convert_md-1.0.0/DEPLOY.md

@@ -0,0 +1,145 @@
+# Installing, updating and removing convert-md
+
+For what convert-md does and how to use it, see [README.md](README.md).
+
+## What gets installed where
+
+Everything is for the current Windows account only; no administrator rights are needed.
+
+| Item | Location |
+|---|---|
+| convert-md code and libraries | Your Python's site-packages (installed by pip) |
+| Right-click menus | `HKEY_CURRENT_USER\Software\Classes\SystemFileAssociations\<ext>\shell\ConvertMd` and `...\ConvertMdToMarkdown` |
+| Hotkey script and its settings | `%LOCALAPPDATA%\ConvertMd\convert-md-hotkey.ahk` and `convert-md.ini` |
+| Hotkey start at login | `convert-md-hotkey.lnk` in your Startup folder (`shell:startup`) |
+| Style templates | `%LOCALAPPDATA%\ConvertMd\templates\` |
+| Log | `%LOCALAPPDATA%\ConvertMd\convert-md.log` |
+
+The menus and hotkey run `pythonw.exe -P -m convert_md ...` using the Python that ran setup.
+The download folder isn't used after installation, so you can move or delete it.
+
+---
+
+## 1. Install
+
+### Option A: installer script (recommended)
+
+1. **Python 3.11 or newer**, the python.org build:
+
+   ```powershell
+   winget install --id Python.Python.3.12 -e --scope user
+   ```
+
+   Open a new PowerShell window and check `py --version` works. If typing `python` opens the
+   Microsoft Store, turn that off in **Settings → Apps → Advanced app settings → App execution aliases**.
+
+2. **Get convert-md**: download **Source code (zip)** from the
+   [latest release](https://github.com/W3i-io/convert-md/releases/latest) and extract it, or
+
+   ```powershell
+   git clone https://github.com/W3i-io/convert-md
+   ```
+
+3. **Run the installer** from that folder:
+
+   ```powershell
+   powershell -ExecutionPolicy Bypass -File .\install.ps1
+   ```
+
+   | Option | Effect |
+   |---|---|
+   | `-NoHotkey` | Right-click menus only; no AutoHotkey |
+   | `-Yes` | Install AutoHotkey without asking if it's missing |
+   | `-Hotkey '^!k'` | Use a different key (AutoHotkey notation: `^` Ctrl, `!` Alt, `+` Shift, `#` Win) |
+   | `-SkipTest` | Skip the test conversions |
+
+### Option B: pip
+
+```powershell
+py -m pip install convert-md
+py -m convert_md setup
+```
+
+For the hotkey, install AutoHotkey first (`winget install AutoHotkey.AutoHotkey -e`), then run setup.
+`pipx install convert-md` followed by `convert-md setup` also works.
+
+### PDF output
+
+PDFs are made through Microsoft Word when it's installed. Without Word, install a PDF engine:
+
+```powershell
+winget install Typst.Typst
+```
+
+### Check it works
+
+```powershell
+py -m convert_md doctor
+```
+
+| Check | Expected |
+|---|---|
+| `doctor` | `OK` for Python, Pandoc, MarkItDown, PDF and Right-click menus (and Hotkey if installed) |
+| Right-click a `.md` file → **Show more options** | **Convert to** submenu |
+| Right-click a `.docx` → **Show more options** | **Convert to Markdown** |
+| Select a file in File Explorer, press **Ctrl+Alt+M** | Convert menu at the mouse pointer |
+
+---
+
+## 2. Update
+
+From a new download or `git pull` in your clone, run the installer again:
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\install.ps1
+```
+
+With pip:
+
+```powershell
+py -m pip install --upgrade convert-md
+py -m convert_md setup
+```
+
+Setup replaces the menus, hotkey script and Startup shortcut, and restarts the hotkey.
+
+## 3. Moving to a new Python version
+
+The menus point at a specific Python. After installing a new Python version (for example 3.12 to 3.13),
+run the installer again, or `py -m pip install convert-md` followed by `py -m convert_md setup`.
+`doctor` reports **Right-click menus: point at a different Python** when this is needed.
+
+## 4. Uninstall
+
+```powershell
+powershell -ExecutionPolicy Bypass -File .\uninstall.ps1
+```
+
+This removes the right-click menus, stops the hotkey and removes it from Startup.
+
+| Option | Also removes |
+|---|---|
+| `-RemovePackage` | The convert-md Python package |
+| `-RemoveData` | `%LOCALAPPDATA%\ConvertMd`: your templates and the log |
+
+Without the script: `py -m convert_md remove`, then `py -m pip uninstall convert-md`.
+Python and AutoHotkey are left installed; remove them in **Settings → Apps** if nothing else uses them.
+
+---
+
+## Troubleshooting
+
+Start with `py -m convert_md doctor`; it names most problems.
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Menu item does nothing | Menus point at a Python that has moved or been removed | Run the installer again |
+| Popup says something failed | See the message, then the log | `%LOCALAPPDATA%\ConvertMd\convert-md.log` |
+| Ctrl+Alt+M does nothing | Hotkey not running | Double-click `%LOCALAPPDATA%\ConvertMd\convert-md-hotkey.ahk`, or run setup again |
+| "convert-md can't find Python" message at login | Python was upgraded or removed | Run the installer again |
+| Ctrl+Alt+M on the desktop shows a tip instead of a menu | The hotkey works in File Explorer windows only | Right-click the file instead |
+| PDF option fails | No Word and no PDF engine | `winget install Typst.Typst` |
+| `convert-md` is not recognised | pip's Scripts folder isn't on PATH | Use `py -m convert_md` instead |
+| Script blocked: "running scripts is disabled" | PowerShell execution policy | Use `powershell -ExecutionPolicy Bypass -File .\install.ps1` |
+| `python` opens the Microsoft Store | Windows app execution alias | Turn it off (step 1) and use `py` |
+| Menus missing on Windows 11 | They're in the classic menu | **Show more options**, Shift + right-click, or Shift + F10 |

convert_md-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 W3i
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

convert_md-1.0.0/MANIFEST.in

@@ -0,0 +1,3 @@
+include CHANGELOG.md DEPLOY.md SECURITY.md RELEASING.md requirements.txt install.ps1 uninstall.ps1
+include samples/Example.md
+recursive-include docs *.md

convert_md-1.0.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: convert-md
+Version: 1.0.0
+Summary: Right-click conversion between Markdown and Word, PDF, Excel, PowerPoint and HTML on Windows, using Pandoc and Microsoft MarkItDown.
+Author: W3i
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/W3i-io/convert-md
+Project-URL: Documentation, https://github.com/W3i-io/convert-md/blob/main/DEPLOY.md
+Project-URL: Issues, https://github.com/W3i-io/convert-md/issues
+Project-URL: Changelog, https://github.com/W3i-io/convert-md/blob/main/CHANGELOG.md
+Keywords: markdown,pandoc,markitdown,docx,pdf,xlsx,pptx,windows,context-menu,converter
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: markitdown[docx,outlook,pdf,pptx,xls,xlsx]<0.2,>=0.1.7
+Requires-Dist: pypandoc_binary>=1.17
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: beautifulsoup4>=4.12
+Requires-Dist: pywin32>=306; sys_platform == "win32"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# convert-md
+
+Right-click conversion between Markdown and Word, PDF, Excel, PowerPoint and HTML on Windows,
+built on [Pandoc](https://pandoc.org) and Microsoft [MarkItDown](https://github.com/microsoft/markitdown).
+
+[![Tests](https://github.com/W3i-io/convert-md/actions/workflows/tests.yml/badge.svg)](https://github.com/W3i-io/convert-md/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/W3i-io/convert-md/blob/main/LICENSE)
+
+## What it does
+
+| Right-click on | Menu | Produces |
+|---|---|---|
+| `.md`, `.markdown` | **Convert to → Word** | `.docx` |
+| | **Convert to → PDF** | `.pdf` (through Microsoft Word, or a Pandoc PDF engine) |
+| | **Convert to → Excel** | `.xlsx`, one sheet per table |
+| | **Convert to → PowerPoint** | `.pptx`, one slide per heading |
+| | **Convert to → Web page** | self-contained `.html` |
+| | **Convert to → All formats** | all of the above |
+| | **Convert to → As set in the file** | the formats the file asks for (see below) |
+| `.docx .pdf .xlsx .xls .pptx .html .htm .csv .epub .msg` | **Convert to Markdown** | `.md` |
+
+![The Convert to submenu on a Markdown file](https://raw.githubusercontent.com/W3i-io/convert-md/main/docs/images/menu-convert-to.png)
+
+![Convert to Markdown on a PowerPoint file](https://raw.githubusercontent.com/W3i-io/convert-md/main/docs/images/menu-to-markdown.png)
+
+- Output is saved next to the original. Nothing is overwritten: a repeat run writes `Report (1).docx`.
+- A small popup confirms what was created and lists any problems.
+- Optional **Ctrl+Alt+M** hotkey: select files in File Explorer and press it to get the same menu at the
+  mouse pointer. Mixed selections work: Markdown files go out, everything else comes in.
+
+| Ctrl+Alt+M on a Markdown file | Ctrl+Alt+M on any other file |
+|---|---|
+| ![Hotkey menu for a Markdown file](https://raw.githubusercontent.com/W3i-io/convert-md/main/docs/images/hotkey-menu.png) | ![Hotkey menu for another file](https://raw.githubusercontent.com/W3i-io/convert-md/main/docs/images/hotkey-to-markdown.png) |
+
+## Install
+
+Needs Windows 10 or 11 and Python 3.11 or newer from python.org
+(`winget install --id Python.Python.3.12 -e --scope user`).
+
+1. Download the latest release from the [Releases page](https://github.com/W3i-io/convert-md/releases)
+   (**Source code (zip)**) and extract it, or `git clone https://github.com/W3i-io/convert-md`.
+2. In PowerShell, in that folder:
+
+   ```powershell
+   powershell -ExecutionPolicy Bypass -File .\install.ps1
+   ```
+
+The installer sets everything up for your Windows account only (no administrator rights), offers to
+install [AutoHotkey v2](https://www.autohotkey.com) for the hotkey, and runs a test conversion.
+Use `-NoHotkey` for the right-click menus only.
+
+Prefer pip? Once it's published to PyPI:
+
+```powershell
+py -m pip install convert-md
+py -m convert_md setup
+```
+
+Updating, moving, uninstalling and troubleshooting: see [DEPLOY.md](https://github.com/W3i-io/convert-md/blob/main/DEPLOY.md).
+
+On Windows 11 the menu entries are under **Show more options**, Shift + right-click, or Shift + F10.
+
+## Choosing formats inside the file
+
+**Convert to → As set in the file** reads `outputs:` from the front-matter first, then the filename,
+and otherwise makes a Word document.
+
+```markdown
+---
+outputs: [docx, pdf, xlsx]
+---
+```
+
+Or name the file `Proposal.docx.pdf.md` to get `Proposal.docx` and `Proposal.pdf`.
+
+## House styling
+
+```powershell
+convert-md templates
+```
+
+creates starter `reference.docx` and `reference.pptx` in `%LOCALAPPDATA%\ConvertMd\templates` and opens the
+folder. Change their **styles** (fonts, heading colours, margins, slide masters) in Word or PowerPoint,
+not their text. From then on every conversion uses them, and Word-made PDFs follow the Word styles.
+Add a `style.css` in the same folder to style HTML output.
+
+## Command line
+
+```powershell
+convert-md --to docx Report.md
+convert-md --to docx,pdf,xlsx Report.md
+convert-md --to all Report.md
+convert-md --to md Contract.pdf Deck.pptx
+convert-md doctor          # check the installation
+```
+
+If `convert-md` isn't found, use `py -m convert_md` instead: pip may have put the command in a folder
+that isn't on your PATH.
+
+## Known limitations
+
+| Area | Limitation |
+|---|---|
+| Platform | The menus and hotkey are Windows only. The command line also works on macOS and Linux. |
+| Windows 11 menu | Entries appear under **Show more options**, not in the compact top-level menu. |
+| Excel output | Only tables are exported. Text, lists and images outside tables are left out; there are no formulas. |
+| PDF output | Needs Microsoft Word, or a PDF engine such as Typst (`winget install Typst.Typst`). Engine-made PDFs look different from Word-made ones. |
+| PowerPoint output | One slide per heading with Pandoc's default layout; long sections overflow the slide. Use `reference.pptx` for your own master. |
+| Scanned PDFs | Image-only PDFs have no text to extract; run OCR on them first. |
+| Conversion quality | Complex layouts (multi-column PDFs, merged table cells, text boxes, charts) come through partially or as plain text. |
+| Protected files | Password-protected or rights-managed documents can't be converted. |
+| Legacy formats | Old `.doc` and `.ppt` files aren't supported; save them as `.docx` / `.pptx` first. |
+| Several files at once | Windows starts one conversion per file from the right-click menu, so each shows its own popup. |
+| Hotkey | Needs AutoHotkey v2. Works in File Explorer windows only: not on the desktop, in Open/Save dialogs or in other file managers. |
+| Output folder | Files are written next to the original, so read-only folders fail. |
+| Remote images | Images linked by URL in Markdown are downloaded by Pandoc when embedded. |
+
+## Privacy and security
+
+Conversions run entirely on your PC; convert-md sends nothing anywhere. It changes the registry only
+under your own account (`HKEY_CURRENT_USER`). See [SECURITY.md](https://github.com/W3i-io/convert-md/blob/main/SECURITY.md)
+for details and how to report a vulnerability.
+
+## Credits and licence
+
+convert-md is MIT licensed. It relies on [Pandoc](https://pandoc.org) (GPL, installed separately through
+`pypandoc_binary`), [MarkItDown](https://github.com/microsoft/markitdown) (MIT),
+[openpyxl](https://openpyxl.readthedocs.io), [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/),
+[pywin32](https://github.com/mhammond/pywin32) and, for the hotkey, [AutoHotkey](https://www.autohotkey.com) (GPL).

convert_md-1.0.0/README.md

@@ -0,0 +1,129 @@
+# convert-md
+
+Right-click conversion between Markdown and Word, PDF, Excel, PowerPoint and HTML on Windows,
+built on [Pandoc](https://pandoc.org) and Microsoft [MarkItDown](https://github.com/microsoft/markitdown).
+
+[![Tests](https://github.com/W3i-io/convert-md/actions/workflows/tests.yml/badge.svg)](https://github.com/W3i-io/convert-md/actions/workflows/tests.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/W3i-io/convert-md/blob/main/LICENSE)
+
+## What it does
+
+| Right-click on | Menu | Produces |
+|---|---|---|
+| `.md`, `.markdown` | **Convert to → Word** | `.docx` |
+| | **Convert to → PDF** | `.pdf` (through Microsoft Word, or a Pandoc PDF engine) |
+| | **Convert to → Excel** | `.xlsx`, one sheet per table |
+| | **Convert to → PowerPoint** | `.pptx`, one slide per heading |
+| | **Convert to → Web page** | self-contained `.html` |
+| | **Convert to → All formats** | all of the above |
+| | **Convert to → As set in the file** | the formats the file asks for (see below) |
+| `.docx .pdf .xlsx .xls .pptx .html .htm .csv .epub .msg` | **Convert to Markdown** | `.md` |
+
+![The Convert to submenu on a Markdown file](https://raw.githubusercontent.com/W3i-io/convert-md/main/docs/images/menu-convert-to.png)
+
+![Convert to Markdown on a PowerPoint file](https://raw.githubusercontent.com/W3i-io/convert-md/main/docs/images/menu-to-markdown.png)
+
+- Output is saved next to the original. Nothing is overwritten: a repeat run writes `Report (1).docx`.
+- A small popup confirms what was created and lists any problems.
+- Optional **Ctrl+Alt+M** hotkey: select files in File Explorer and press it to get the same menu at the
+  mouse pointer. Mixed selections work: Markdown files go out, everything else comes in.
+
+| Ctrl+Alt+M on a Markdown file | Ctrl+Alt+M on any other file |
+|---|---|
+| ![Hotkey menu for a Markdown file](https://raw.githubusercontent.com/W3i-io/convert-md/main/docs/images/hotkey-menu.png) | ![Hotkey menu for another file](https://raw.githubusercontent.com/W3i-io/convert-md/main/docs/images/hotkey-to-markdown.png) |
+
+## Install
+
+Needs Windows 10 or 11 and Python 3.11 or newer from python.org
+(`winget install --id Python.Python.3.12 -e --scope user`).
+
+1. Download the latest release from the [Releases page](https://github.com/W3i-io/convert-md/releases)
+   (**Source code (zip)**) and extract it, or `git clone https://github.com/W3i-io/convert-md`.
+2. In PowerShell, in that folder:
+
+   ```powershell
+   powershell -ExecutionPolicy Bypass -File .\install.ps1
+   ```
+
+The installer sets everything up for your Windows account only (no administrator rights), offers to
+install [AutoHotkey v2](https://www.autohotkey.com) for the hotkey, and runs a test conversion.
+Use `-NoHotkey` for the right-click menus only.
+
+Prefer pip? Once it's published to PyPI:
+
+```powershell
+py -m pip install convert-md
+py -m convert_md setup
+```
+
+Updating, moving, uninstalling and troubleshooting: see [DEPLOY.md](https://github.com/W3i-io/convert-md/blob/main/DEPLOY.md).
+
+On Windows 11 the menu entries are under **Show more options**, Shift + right-click, or Shift + F10.
+
+## Choosing formats inside the file
+
+**Convert to → As set in the file** reads `outputs:` from the front-matter first, then the filename,
+and otherwise makes a Word document.
+
+```markdown
+---
+outputs: [docx, pdf, xlsx]
+---
+```
+
+Or name the file `Proposal.docx.pdf.md` to get `Proposal.docx` and `Proposal.pdf`.
+
+## House styling
+
+```powershell
+convert-md templates
+```
+
+creates starter `reference.docx` and `reference.pptx` in `%LOCALAPPDATA%\ConvertMd\templates` and opens the
+folder. Change their **styles** (fonts, heading colours, margins, slide masters) in Word or PowerPoint,
+not their text. From then on every conversion uses them, and Word-made PDFs follow the Word styles.
+Add a `style.css` in the same folder to style HTML output.
+
+## Command line
+
+```powershell
+convert-md --to docx Report.md
+convert-md --to docx,pdf,xlsx Report.md
+convert-md --to all Report.md
+convert-md --to md Contract.pdf Deck.pptx
+convert-md doctor          # check the installation
+```
+
+If `convert-md` isn't found, use `py -m convert_md` instead: pip may have put the command in a folder
+that isn't on your PATH.
+
+## Known limitations
+
+| Area | Limitation |
+|---|---|
+| Platform | The menus and hotkey are Windows only. The command line also works on macOS and Linux. |
+| Windows 11 menu | Entries appear under **Show more options**, not in the compact top-level menu. |
+| Excel output | Only tables are exported. Text, lists and images outside tables are left out; there are no formulas. |
+| PDF output | Needs Microsoft Word, or a PDF engine such as Typst (`winget install Typst.Typst`). Engine-made PDFs look different from Word-made ones. |
+| PowerPoint output | One slide per heading with Pandoc's default layout; long sections overflow the slide. Use `reference.pptx` for your own master. |
+| Scanned PDFs | Image-only PDFs have no text to extract; run OCR on them first. |
+| Conversion quality | Complex layouts (multi-column PDFs, merged table cells, text boxes, charts) come through partially or as plain text. |
+| Protected files | Password-protected or rights-managed documents can't be converted. |
+| Legacy formats | Old `.doc` and `.ppt` files aren't supported; save them as `.docx` / `.pptx` first. |
+| Several files at once | Windows starts one conversion per file from the right-click menu, so each shows its own popup. |
+| Hotkey | Needs AutoHotkey v2. Works in File Explorer windows only: not on the desktop, in Open/Save dialogs or in other file managers. |
+| Output folder | Files are written next to the original, so read-only folders fail. |
+| Remote images | Images linked by URL in Markdown are downloaded by Pandoc when embedded. |
+
+## Privacy and security
+
+Conversions run entirely on your PC; convert-md sends nothing anywhere. It changes the registry only
+under your own account (`HKEY_CURRENT_USER`). See [SECURITY.md](https://github.com/W3i-io/convert-md/blob/main/SECURITY.md)
+for details and how to report a vulnerability.
+
+## Credits and licence
+
+convert-md is MIT licensed. It relies on [Pandoc](https://pandoc.org) (GPL, installed separately through
+`pypandoc_binary`), [MarkItDown](https://github.com/microsoft/markitdown) (MIT),
+[openpyxl](https://openpyxl.readthedocs.io), [Beautiful Soup](https://www.crummy.com/software/BeautifulSoup/),
+[pywin32](https://github.com/mhammond/pywin32) and, for the hotkey, [AutoHotkey](https://www.autohotkey.com) (GPL).

convert_md-1.0.0/RELEASING.md

@@ -0,0 +1,66 @@
+# Releasing convert-md
+
+For maintainers. Releases are built and published by GitHub Actions when a version tag is pushed.
+
+## Every release
+
+1. Make sure the **Tests** workflow is green on `main`.
+2. Update the version in `src/convert_md/__init__.py` (for example `1.0.1`), following
+   [Semantic Versioning](https://semver.org/): fixes bump the last number, new features the middle one,
+   breaking changes the first.
+3. In `CHANGELOG.md`, move the items under **Unreleased** into a new `## [1.0.1] - YYYY-MM-DD` section
+   and update the links at the bottom.
+4. Commit, tag and push:
+
+   ```powershell
+   git commit -am "Release 1.0.1"
+   git tag v1.0.1
+   git push origin main --tags
+   ```
+
+The **Release** workflow then:
+
+| Job | Does |
+|---|---|
+| build | Checks the tag matches the version, builds the wheel and source package, runs `twine check` |
+| github-release | Creates the GitHub release with notes from `CHANGELOG.md` and attaches the packages |
+| pypi | Publishes to PyPI (only when PyPI publishing is turned on, below) |
+
+If the tag doesn't match the version, the workflow stops before anything is published. Delete the tag
+(`git tag -d v1.0.1` and `git push origin :refs/tags/v1.0.1`), fix the version, and tag again.
+
+## One-time PyPI setup
+
+The PyPI project name is **convert-md**, the same as the repository and the command.
+(The working name `md-convert` couldn't be used: PyPI already has `mdconvert` and treats names that
+differ only by `-`, `_` or `.` as the same.)
+
+Publishing uses PyPI trusted publishing, so no API token is stored in GitHub.
+
+1. Create a PyPI account at https://pypi.org (turn on two-factor authentication).
+2. Go to **Your account → Publishing → Add a new pending publisher** and enter:
+
+   | Field | Value |
+   |---|---|
+   | PyPI project name | `convert-md` |
+   | Owner | `W3i-io` |
+   | Repository name | `convert-md` |
+   | Workflow name | `release.yml` |
+   | Environment name | `pypi` |
+
+3. In the GitHub repository: **Settings → Environments → New environment** named `pypi`.
+   Optionally add yourself as a required reviewer so each PyPI upload waits for approval.
+4. **Settings → Secrets and variables → Actions → Variables → New repository variable**:
+   `PUBLISH_TO_PYPI` = `true`.
+5. Publish by re-running the **Release** workflow for the current tag, or with the next tag.
+
+To rehearse first, register the same pending publisher on https://test.pypi.org and temporarily add
+`repository-url: https://test.pypi.org/legacy/` under the `pypa/gh-action-pypi-publish` step.
+
+## Repository settings worth turning on
+
+| Setting | Where |
+|---|---|
+| Private vulnerability reporting | **Settings → Code security → Private vulnerability reporting** (used by SECURITY.md) |
+| Dependabot alerts and security updates | **Settings → Code security** |
+| Branch protection for `main`, requiring the Tests workflow | **Settings → Branches** |

convert_md-1.0.0/SECURITY.md

@@ -0,0 +1,38 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are made in the latest release. Please update before reporting.
+
+| Version | Supported |
+|---|---|
+| 1.x (latest) | Yes |
+| Earlier | No |
+
+## Reporting a vulnerability
+
+Please report security problems privately, not in a public issue:
+on GitHub, open the repository's **Security** tab and choose **Report a vulnerability**.
+
+Include the convert-md version (`convert-md --version`), your Windows and Python versions, and the steps
+or a sample file that shows the problem. We aim to acknowledge reports within a week and will keep you
+informed while a fix is prepared. Please give us a reasonable chance to release a fix before disclosing
+the issue publicly.
+
+## How convert-md behaves
+
+| Area | Behaviour |
+|---|---|
+| Network | convert-md makes no network requests of its own and sends nothing anywhere. Pandoc downloads images that a Markdown file links to by URL when it embeds them in the output. |
+| Permissions | Installs and runs as the current user. No administrator rights; registry changes are limited to `HKEY_CURRENT_USER\Software\Classes\SystemFileAssociations`. |
+| Startup | The optional hotkey adds one shortcut to the user's Startup folder, which runs an AutoHotkey script in `%LOCALAPPDATA%\ConvertMd`. |
+| Files | Reads only the files you choose. Writes new files next to them and never overwrites existing files. Writes a log of file paths and errors to `%LOCALAPPDATA%\ConvertMd`. |
+| Code loading | The menus and hotkey run Python with `-P`, so a file named `convert_md.py` placed in a document's folder can't be run in place of convert-md. MarkItDown plugins are disabled. |
+| PDF through Word | Word opens only the `.docx` that convert-md has just generated, read-only. Macros in your source documents are never run. |
+
+## Converting untrusted documents
+
+convert-md passes documents to Pandoc, MarkItDown and the libraries they use (for example PDF and Office
+parsers). A deliberately malformed document could exploit a bug in one of those libraries. Keep convert-md
+and its dependencies up to date (run the installer again, or `py -m pip install --upgrade convert-md`),
+and take the same care with unknown files as you would when opening them in any other program.

convert_md-1.0.0/docs/screenshots.md

@@ -0,0 +1,20 @@
+# Screenshots
+
+Images used in the README live in `docs/images/`. They are referenced by absolute
+`raw.githubusercontent.com` URLs so they also show on PyPI.
+
+| File | Shows | Status |
+|---|---|---|
+| `menu-convert-to.png` | The **Convert to** submenu on a `.md` file | Done |
+| `menu-to-markdown.png` | **Convert to Markdown** on a PowerPoint file | Done |
+| `hotkey-menu.png` | The Ctrl+Alt+M menu for a Markdown file | Done |
+| `hotkey-to-markdown.png` | The Ctrl+Alt+M menu for any other file | Done |
+| `before-after.png` | A Markdown file beside the Word document it produced | Optional |
+| `excel-output.png` | The Excel output: one sheet per table, numbers formatted | Optional |
+| `demo.gif` | 10–15 seconds: right-click → Convert to → Word → popup → open the result (under 5 MB) | Optional |
+
+Tips for new screenshots:
+- Use example files, so no real documents or names appear.
+- Hide anything personal: your user name in the address bar, other files in the folder, the taskbar.
+- Use the same Windows theme for all of them (the current set is dark).
+- Crop tightly to the menu or window; about 800–1200 px wide reads well on GitHub.