Copying the visible words can lose a link destination or flatten headings into ordinary lines. Start with the page's actual content structure so the new document keeps the relationships readers need.
Convert a local content file
With Pandoc installed, this command reads instructions.html and writes a separate Markdown file:
pandoc --from=html --to=gfm --wrap=none instructions.html --output=instructions.md
The explicit formats avoid relying on filename guesses. gfm selects GitHub Flavored Markdown; --wrap=none avoids inserting line wrapping into ordinary prose. Pandoc's manual documents the input, output, and wrapping options. Pandoc conversion options
Keep the HTML source while you review the conversion. If the command is unavailable, install Pandoc using its official installation instructions, then open a terminal where the executable is available.
Compare a small source with the expected structure
This original fixture contains a heading, a linked instruction, and a command whose angle brackets must stay literal:
<h1>Equipment handover</h1>
<p>Read the <a href="https://example.com/handover">handover notes</a>.</p>
<h2>Check the label</h2>
<pre><code>label <item-id></code></pre>
Running that fixture through Pandoc 3.10 with the command above produced:
# Equipment handover
Read the [handover notes](https://example.com/handover).
## Check the label
label <item-id>
Fence characters or whitespace may differ between converter settings. Judge the structure and content: one level-one title, one level-two section, the same link target, and a code block displaying the literal placeholder.
The example.com destination is a fixture, not an operational handover link. Replace it with the real intended destination in your document.
Extract the content you actually want to move
If the source is a complete website page, identify the article or instruction section before conversion. Navigation, footers, and repeated menus are content too; a converter cannot know which of those your README needs without an extraction decision.
Make a copy containing the intended heading and body sections. Retain a missing warning or footnote if it changes how the instructions work. Removing surrounding clutter is useful only while the meaning survives.
For a page whose text is inserted by JavaScript, inspect whether the saved HTML contains the finished words. Converting an empty content container cannot recover the text you saw in the browser. Obtain an appropriate source copy with the content included.
Inspect links and images in their new location
A relative link such as guide.html may have worked beside the original HTML file. In a repository, its target may be a different path or a Markdown file. Decide where each destination will live, then update the path and test it from the rendered README.
Do the same for images. Copying a Markdown reference does not place the referenced image in the repository. Check the file location, capitalization, and alternative text in the actual destination.
When you need the reverse transformation later, converting Markdown to HTML covers rendering the document back as a page.
Treat complex tables and interactive elements separately
Pandoc warns that conversions between formats can lose information, including formatting and complex table structure. Pandoc's conversion limits
For a table with merged cells, decide what each row must mean in the README. Split a group heading into an explicit column or retain an appropriate HTML table if your destination supports it. Do not accept a flattened table until labels still match their values.
A form, interactive chart, or tabbed page also needs a decision. Preserve the explanation and necessary results in readable text; link to the working interface where it is still needed. Markdown prose cannot carry the original interaction merely by containing its button label.
Finish in the destination preview
Read the converted document where people will use it. Check heading levels, link destinations, list nesting, literal code characters, and table relationships against the source. Keep the original HTML until those checks pass and the Markdown contains the instructions you intended to move.