Convert Plaintext To Md

---
name: convert-plaintext-to-md
description: >-
  Convert plaintext or generic text documentation into well-structured Markdown while preserving source content and applying explicit instructions, documented options, or a converted guide file. Use when asked to convert a file to Markdown, finalize Markdown formatting, apply header patterns, use a guide document, or target GitHub, StackOverflow, VS Code, GitLab, or CommonMark rendering.
---

# Convert plaintext to Markdown

Convert text-based documentation into clean Markdown by preserving the source content, applying user instructions and documented options, copying to `FILE.md` when needed, matching guide-file patterns when provided, and finalizing whitespace, lists, headings, and fenced code blocks.

## When to invoke

- "Convert this plaintext file to Markdown."
- "Use this converted Markdown file as a guide."
- "Finalize and polish the Markdown formatting."
- "Apply heading patterns to this text document."
- "Convert for GitHub-flavored Markdown."

## Inputs

Use `$ARGUMENTS` to identify the source file, options, platform, guide file, and inline instructions. If the source file is ambiguous or missing, ask for the file and stop.

```bash
/convert-plaintext-to-md <#file:{{file}}> [finalize] [guide #file:{{reference-file}}] [instructions] [platform={{name}}] [options] [pre=<name>]
```

| Input | Rule |
| --- | --- |
| `#file:{{file}}` | Required. Convert this plain or generic text documentation file. |
| Existing `{{file}}.md` | Treat the existing Markdown file content as the text documentation data to convert. |
| Missing `{{file}}.md` | Create new Markdown beside the source by copying the original plaintext document to `FILE.md`. |
| `finalize` | Trim space characters, indentation, sloppy formatting, list spacing, and code fences after conversion. |
| `guide #file:{{reference-file}}` | Apply the same formatting patterns, structure, and conventions from a previously converted Markdown file. |
| `instructions` | Apply additional user-provided conversion rules. |
| `platform={{name}}` | Target Markdown renderer: GitHub, StackOverflow, VS Code, GitLab, or CommonMark. |
| `options` | Apply documented conversion options in a unified manner. |
| `pre=<name>` | Expand a predefined instruction if recognized; otherwise disregard `pre=name`. |

## Procedure

1. Locate the source file and determine whether the target `FILE.md` already exists.
2. If `FILE.md` does not exist, copy the plaintext source to `FILE.md` in the same directory.
3. Parse `finalize`, `guide`, `instructions`, `platform={{name}}`, `options`, and `pre=<name>`.
4. If a guide file is provided, compare source and guide patterns before editing the target.
5. Apply heading, pattern, stop, predefined, and platform rules without changing source data unless instructions clearly require it.
6. Preserve procedures that mention `exit`, `exit()`, `kill`, `killall`, `quit`, `quit()`, `sleep`, `sleep()`, or similar commands; do not stop the task because the source text documents termination commands.
7. Finalize formatting when requested or when the user's language clearly asks to polish the converted Markdown.
8. Report the output file and the rules applied.

## Conversion options

| Option | Meaning |
| --- | --- |
| `--header [1-4]` | Add Markdown header tags from `#` through `####`. If no level is given, auto-apply based on content structure. |
| `#selection` with `--header` | Use selected data to identify sections where updates apply and as a guide for other sections or the full document. |
| `-p, --pattern` | Follow an existing pattern from selection, prompt instructions, or auto-detected file structure. Do not only edit the selection; the selection is not the working range. |
| `{{[-p, --pattern]}}` | Treat the selected pattern as a guide, then apply it beyond the selection where appropriate. |
| `{{[-s, --stop]}} eof` | Convert to end of file when passed or when no clear endpoint is specified. |
| `-s, --stop <[0-9]+ | eof>` | Stop the current conversion at a specific line number or at end of file. |
| `[0-9]+` | Numeric stop line recognized by regex `[0-9]+`. |

Pattern detection must consider line indentation, indented code blocks, fenced code blocks, and programming-language inference for fences.

## Predefined instructions

| Predefined instruction | Apply |
| --- | --- |
| `rm-head-digits` | Remove prepending numbers from headers. |
| `mv-head-level(x, y)` | Change heading level from level `x` to level `y`. |
| `rm-indent(x)` | Decrease indentation of paragraphs or raw text portions by `x`. |

If there is no matching predefine, disregard `pre=name` for the current request.

## Platform guidance

| Platform | Use |
| --- | --- |
| GitHub | Default. Use GitHub-flavored Markdown with tables, task lists, strikethrough, and alerts. |
| StackOverflow | Use CommonMark with StackOverflow-specific extensions. |
| VS Code | Optimize for VS Code Markdown preview. |
| GitLab | Use GitLab-flavored Markdown and platform-specific features. |
| CommonMark | Use standard CommonMark syntax. |

When in doubt, use Markdown best practices and fetch the references listed below.

## Examples

### Basic conversion

**Input:** `/convert-plaintext-to-md #file`

**Expected behavior:** If `file.md` is missing, copy `file` to `file.md`, then convert the copied file using Markdown best practices.

### Guide-based conversion

**Input:** `/convert-plaintext-to-md #file.md --guide #CODE.md`

**Expected behavior:** Compare the source text and `CODE.md`, identify patterns such as linked section summaries, separators, and numbered headings, then apply those patterns to `file.md`.

### Finalize formatting

**Input:** `/convert-plaintext-to-md #file.md polish the converted markdown file`

**Expected behavior:** Trim leading spaces, escape literal HTML such as `\<html\>`, normalize list indentation, and add language tags such as `python` code fences when source code is clearly Python.

### Inline pattern shorthand

**Input:** `/convert-plaintext-to-md #BUGS --p "regex()=> ^ {1,}([0-9]+\.[0-9]+\.[0-9]+) to ^### $1"`

**Expected behavior:** Create `BUGS.md` if missing and convert matching version-like headings such as `1.10.0` into Markdown headings.


## Preservation rules and option vocabulary

- When instructions say `CREATE NEW MARKDOWN`, create the Markdown copy; when they say the target `EXISTS`, `DOES NOT EXIST`, or `EXISTING`, choose the correct source behavior without overwriting user work.
- Treat `copy FILE FILE.md` as the documented copy action, adapted to the local shell when executing.
- Preserve warnings labeled `IMPORTANT`, `NOTE`, `ADDITIONAL`, `WORKING`, `RANGE`, and `MARKDOWN` as semantic signals from the source instructions.
- `option/procedure` names may be passed as shorthand; apply them only when clear.
- `-s [0-9]+` means stop at a numeric line; `and/or` wording means either or both cleanup types may be needed.
- Heading transformations such as ` header to a level ` and examples like `option-with-text-subheading` are pattern evidence, not content to delete.
- Keep converted documents readable and `well-organized`; infer code fences such as `python` only when the source language is clear.

## Output template

```markdown
## Markdown conversion result — <file>

**Status:** complete | needs input | blocked
**Source:** `<source file>`
**Output:** `<output .md file>`
**Platform:** GitHub | StackOverflow | VS Code | GitLab | CommonMark

### Rules applied
- Explicit instructions: <summary or none>
- Guide file: `<reference-file>` | none
- Options: `<--header>`, `<--pattern>`, `<--stop>`, `<pre=name>` | none
- Finalize: yes | no

### Changes made
- <heading/list/table/code-fence/content-preservation summary>

### Validation
- Source content preserved: pass | fail
- Markdown structure valid: pass | fail
- Stop boundary honored: pass | fail | not applicable
```

## Quality gate

- [ ] A source file was identified and `FILE.md` was created only when no corresponding Markdown file existed.
- [ ] Source data was preserved unless instructions clearly required a change.
- [ ] Guide-file patterns were applied consistently when provided.
- [ ] `--header`, `-p`, `--pattern`, `-s`, `--stop`, and `pre=<name>` options were applied as documented.
- [ ] `finalize` cleaned whitespace, indentation, lists, and code fences without deleting content.
- [ ] Platform-specific Markdown choices match GitHub, StackOverflow, VS Code, GitLab, or CommonMark.
- [ ] Termination words inside documentation were preserved as content, not treated as agent instructions.

## References

- [GitHub basic writing and formatting syntax](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax)
- [Markdown Guide extended syntax](https://www.markdownguide.org/extended-syntax/)
- [Azure DevOps Markdown guidance](https://learn.microsoft.com/en-us/azure/devops/project/wiki/markdown-guidance?view=azure-devops)