102 lines
5.6 KiB
Markdown
102 lines
5.6 KiB
Markdown
# Markdown Converter - User Manual
|
|
|
|
## 1. Overview and Purpose
|
|
|
|
**Markdown Converter** is a desktop application designed to automate and standardize the creation of professional documents. It allows users to write content in the simple and clean Markdown format and convert it into beautifully formatted `.docx` and `.pdf` documents, using an advanced template and profile system.
|
|
|
|
The main goal is to eliminate the need for manual, repetitive formatting in a word processor, ensuring consistency across documents and speeding up the workflow, especially for technical documentation, user manuals, and reports.
|
|
|
|
## 2. System Requirements
|
|
|
|
To use all the application's features, ensure the following components are present on your system:
|
|
|
|
* **Python 3.8+**: Required to run the application.
|
|
* **wkhtmltopdf**: Essential for the direct Markdown to PDF conversion. It must be installed and preferably added to the system's PATH.
|
|
* **Microsoft Word** OR **LibreOffice**: At least one of these software packages is required for the high-fidelity conversion from `.docx` to `.pdf`. The application will automatically detect which software is available.
|
|
|
|
## 3. Installation and Launch
|
|
|
|
1. **Clone the Repository**: Get a local copy of the project from the Gitea server.
|
|
2. **Create a Virtual Environment**: It is good practice to isolate the project's dependencies.
|
|
```bash
|
|
python -m venv venv
|
|
# On Windows
|
|
venv\Scripts\activate
|
|
# On Linux/macOS
|
|
source venv/bin/activate
|
|
```
|
|
3. **Install Dependencies**:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
4. **Run the Application**:
|
|
```bash
|
|
python -m markdownconverter
|
|
```
|
|
|
|
## 4. The User Interface
|
|
|
|
The main interface is divided into logical sections to guide the user through the conversion process.
|
|
|
|
### 4.1. Profile & Source File
|
|
|
|
This is the starting section where you define the context of your work.
|
|
|
|
* **Active Profile**: A dropdown menu to select the conversion profile to use. A profile is a set of configurations that links a template to its placeholder values.
|
|
* **Manage...**: Opens the profile management window, where you can create, rename, and delete profiles.
|
|
* **Markdown File**: The field to select the source `.md` file containing your content.
|
|
* **Browse...**: Opens a dialog to browse for the `.md` file on your computer.
|
|
|
|
### 4.2. Placeholders
|
|
|
|
This panel is **dynamic** and represents the core of the application. Once a valid profile is selected, this panel automatically populates with all placeholders (`%%...%%`) found in the associated template.
|
|
|
|
* **Dynamic Placeholders**: Editable text fields where you enter values (e.g., project name, revision number).
|
|
* **Structural Placeholders**: Read-only fields (`<Automatic>`) indicating anchor points for auto-generated content, such as the revision history (`%%REVISION_RECORD%%`) and the table of contents (`%%DOC_TOC%%`).
|
|
|
|
### 4.3. Options
|
|
|
|
* **Add TOC**: If checked, a Table of Contents will be generated and inserted into the final document.
|
|
* **Open Source Folder**: Opens the folder containing the source Markdown file.
|
|
|
|
### 4.4. Conversion Actions
|
|
|
|
This section contains the buttons to perform conversions. Each action has a text field showing the proposed output path (which can be edited) and an "Open" button to open the generated file.
|
|
|
|
* **MD → DOCX**: Converts the Markdown file into a `.docx` document using the active profile's template and values.
|
|
* **MD → PDF**: Converts the Markdown file directly into a clean `.pdf`, without using the DOCX template.
|
|
* **DOCX → PDF**: Converts the generated `.docx` file into a high-fidelity `.pdf`. This button is enabled only after a successful MD → DOCX conversion.
|
|
|
|
### 4.5. Log Viewer
|
|
|
|
Displays real-time log messages from the application, which is useful for monitoring the process and diagnosing any issues.
|
|
|
|
## 5. Recommended Workflow
|
|
|
|
1. **Create a DOCX Template**: Prepare a `.docx` file with your desired formatting (styles, headers, footers) and insert placeholders at the appropriate locations (e.g., `%%DOC_PROJECT%%`). Don't forget to include the structural placeholders `%%REVISION_RECORD%%`, `%%DOC_TOC%%`, and `%%DOC_CONTENT%%`.
|
|
|
|
2. **Create a Profile**:
|
|
* Launch the application and click **"Manage..."**.
|
|
* In the "Manage Profiles" window, click **"New..."**.
|
|
* Give the profile a descriptive name (e.g., "Product Alpha Manual").
|
|
* Select the `.docx` template file you created.
|
|
|
|
3. **Work with the Profile**:
|
|
* In the main window, select your new profile from the **"Active Profile"** dropdown.
|
|
* The "Placeholders" area will populate automatically. Fill in the values for your specific document.
|
|
* Select the `.md` file you want to convert.
|
|
* The output paths will be generated automatically, but you can edit them if needed.
|
|
|
|
4. **Convert and Finalize**:
|
|
* Click **"MD → DOCX"**. The application will generate the `.docx` file. The values you entered will be saved to the profile for future use.
|
|
* Click "Open" next to the DOCX path to open it in Word or LibreOffice.
|
|
* **Crucial Step:** Update the table of contents (usually by right-clicking it and selecting "Update Field"). Make any other minor manual adjustments and save the file.
|
|
* Return to the application and click **"DOCX → PDF"**. This will create the final PDF version, identical to the DOCX you just reviewed.
|
|
|
|
## 6. Profile Management
|
|
|
|
The **"Manage Profiles"** window allows you to:
|
|
* **New...**: Create a new profile, associating it with a name and a template.
|
|
* **Rename...**: Rename an existing profile without losing its saved values.
|
|
* **Delete**: Permanently remove a profile. This action will require confirmation.
|