DOCSEARCHbyAlgolia
Submit Docs

md2docx

repository·master·Indexed 42 days ago

https://github.com/nihole/md2docx

A tool for converting Git-based Markdown documentation into professional Microsoft Word documents. It uses Pandoc for initial conversion and a Python-based orchestrator (render.py) to inject content into Word templates via a structure.yml configuration. Features include automated table and figure captions, field updates, and support for extended Markdown plugins such as footnotes, subscripts, and custom containers.

Tokens
1.4K
Snippets
3
Records
6
Agent score
51%

What's inside md2docx

  1. Understand the project file structure

    master

    When setting up a new documentation project using the example template, you will interact with these files:

    • mkword.py: The entry point script. You must edit this to update the path to render.py and the path to your Markdown source.
    • render.py: The core engine. This is a static file; you typically do not need to modify it, but you must provide its path in mkword.py.
    • structure.yml: The configuration file defining how render.py behaves and how the document is structured.
    • templates/template.docx: Your Word template. This file should contain all the corporate styles and manual section divisions (chapters) that the script will fill.
    • media/: A folder containing images used in your Markdown files.
    • *.md: Your source Markdown files containing the actual documentation content.

  2. Extended Markdown Plugins supported by md2docx

    master

    The conversion process supports several extended Markdown features typically provided by markdown-it plugins:

    • Emojis: Supports classic markup (e.g., :wink:) and emoticons (e.g., ;)).
    • Subscript & Superscript: Use ^text^ for superscript and ~text~ for subscript.
    • Inserted Text: Use ++text++ for <ins> tags.
    • Marked Text: Use ==text== for <mark> tags.
    • Footnotes:
      • Reference style: [^label] with definitions [^label]: definition.
      • Inline style: ^[inline definition].
    • Definition Lists:
      • Standard: Term \n : Definition.
      • Compact: Term \n ~ Definition.
    • Abbreviations: Define abbreviations using *[HTML]: Hyper Text Markup Language.
    • Custom Containers: Supports container syntax like ::: warning ... :::.
    • Anchors: Create manual anchors using [text](#anchor) or [text]{#anchor}.

  3. Run the md2docx conversion workflow

    master

    The conversion process follows a high-level workflow where render.py acts as the orchestrator:

    1. Markdown to Docx: render.py uses Pandoc to convert Markdown files into temporary, unstyled .docx files.
    2. Styling and Injection: Using structure.yml and your Word template, render.py injects the content from the temporary files into the correct sections of the template, applying styles, captions, and updating fields.
    3. Cleanup: Temporary files are removed.

    To run the process, use the mkword.py script, passing the path to your structure.yml as an argument.

    Usage Syntax:

    python3 mkword.py <path_to_structure.yml>
    python3 mkword.py structure/structure.yml

  4. Supported Markdown Syntax in md2docx

    master

    The md2docx tool supports a wide range of standard and extended Markdown syntax for conversion to MS Word. Supported features include:

    • Headings: h1 through h6.
    • Horizontal Rules: ___, ---, or ***.
    • Emphasis: Bold (**text** or __text__), Italic (*text* or _text_), and Strikethrough (~~text~~).
    • Blockquotes: Nested blockquotes using >.
    • Lists:
      • Unordered: Using +, -, or *. Sub-lists are created via 2-space indentation.
      • Ordered: Using sequential numbers (e.g., 1., 2.) or repeating 1. for automatic numbering. Supports custom offsets (e.g., 57.).
    • Code:
      • Inline code.
      • Indented code blocks.
      • Fenced code blocks (using
    ) with optional syntax highlighting (e.g., ` ``` js `).
- **Tables**: Supports left-aligned (`| :--- |`) and right-aligned (`| ---: |`) columns.
- **Links & Images**:
    - Standard Markdown links `[text](url)` and links with titles `[text](url "title")`.
    - Images `![alt text](path/to/image.png)`.
- **Typographic Replacements**: When the `typographer` option is enabled, the converter handles symbols like `(c)`, `(tm)`, ellipses `...`, and smart quotes.

  5. Install md2docx on Windows

    master

    To use md2docx for converting Markdown to styled Word documents, follow these setup steps on Windows 10:

    1. Clone the repository to your local machine.
    2. Install Python 3 and ensure the following packages are installed:
      • PyYAML (for YAML parsing)
      • pywin32 (provides win32com.client for MS Word automation)
    3. Install Pandoc (required for the initial Markdown to docx conversion).
    4. Set up your project folder:
      • Copy the example folder from the repository to your local git repository.
      • Rename the folder as needed for your project.
    5. Configure the scripts:
      • Edit mkword.py to point to the correct path of your render.py file.
      • Edit or create your own structure.yml file.
      • Create or edit your Word template (.docx) with the desired corporate styles.
      • Create your Markdown (.md) files.
    # Example of the final execution command
python3 mkword.py structure/structure.yml

  6. Configure render.py via structure.yml

    master

    The render.py script is controlled by a structure.yml file. This file defines the structure of the final Word document and enables specific automation features.

    Available actions in structure.yml:

    • structure_verification: Verifies if the section corresponds to the title.
    • change_data: Inserts data into the specified section.
    • table_style: Applies specific Word styles to tables.
    • table_caption: Converts Markdown captions into native Word table captions.
    • figure_caption: Converts Markdown captions into native Word figure captions.
    • update_fields: Updates all Word fields (e.g., Table of Contents).

    Example configuration snippet:

    actions:
  structure_verification: "yes"
  change_data: "yes"
  table_style: "yes"
  table_caption: "yes"
  figure_caption: "yes"
  update_fields: "yes"
    actions:  
  structure_verification: "yes"  
  change_data: "yes"  
  table_style: "yes"  
  table_caption: "yes"  
  figure_caption: "yes"  
  update_fields: "yes"