Text and regular expressions
Make a README easier to follow with Markdown
Tools to use
Repeated usage questions can mean information is hard to find, not missing. A long introduction and commands buried in prose make it unclear when to begin. Compare source and preview, arranging the document around a reader's first practical task.
Use headings as navigation
# Example Tool
A small example for checking a local text file.
## Before you start
Use a fictional input file.
## Try one example
Follow the steps below.
## If the result differs
Check the input and selected options.Paste the outline into Markdown Preview. The document title should be above preparation, example and troubleshooting sections. Headings communicate hierarchy, not just font size. Action-oriented headings help readers find their task without reading everything from the beginning.
Too many headings interrupt the flow. Give each section one question and its necessary steps. State essential prerequisites briefly, then explain through the result of an example. The preview does not grade writing; read the headings alone to judge whether the workflow is understandable.
Separate input from expected output
## Input
```json
{"name":"demo","enabled":true}
```
## Expected output
```text
Validation succeeded.
```Fenced code blocks preserve the structure of JSON and newlines. Validation succeeded. here is sample documentation, not a validation result produced by this preview. Separate input from output so readers do not copy result lines as commands or data.
Explain where the code belongs and which placeholders must be replaced. Use fictional values, not production credentials or endpoints. Displaying a code block proves no command works; validate documented actions separately in the project's safe test environment.
Use tables for comparisons and lists for steps
| Option | Example | Meaning |
| --- | --- | --- |
| mode | preview | Inspect without applying |
| limit | 10 | Maximum displayed rows |Tables work well when several options share the same comparison columns. Sequential actions are usually clearer as numbered steps. Avoid putting long procedures in table cells, especially when narrow screens would require repeated horizontal scrolling.
mode and limit are fictional documentation examples, not options to copy into a real tool. Replace them with actual supported settings and distinguish sample values from defaults. A reader must know whether 10 is an illustration or the value used when no option is supplied.
A source newline is not always a new paragraph
First line
Second line
Another paragraphThe first two source lines form one paragraph; the blank line starts another. Editor wrapping and semantic paragraph breaks are different. Keep one topic per paragraph and use blank lines to separate topics, checking the preview to see which breaks create structure.
Indentation or an unclosed code fence can absorb later headings into another element. If the rest of the document appears as code, inspect the opening fence rather than only the last line. Change one boundary, indentation or blank line at a time before rewriting whole sections.
Preview restrictions differ from publishing behavior
The preview does not fetch external images or execute raw embedded HTML, and links are not active navigation inside the preview. A missing image therefore does not prove its URL is wrong. HTML output may contain safe links, but publishing-site link checks are a separate task.
The final host may use different Markdown extensions, anchor generation, image handling and CSS. Check structure here, then inspect the publishing destination. This preview cannot guarantee identical styling or the existence of relative-link targets; record what has and has not been verified.
Finally locate four answers as a new reader: prerequisites, input, expected result and next step on failure. Gather scattered answers around the task. A short explanation at a confusing decision can help more than extra general prose; use the preview to assess that reorganization.