Documenting a project's files, tables and links

A README, a handover note or a wiki page explains a project to the next person: what’s where, how the pieces fit, and where to read more. Most of that is a picture of the folders, a table or two and a list of links, and each is fiddly to type by hand. These tools make each part from what you already have, in your browser, ready to paste into Markdown, the plain text format that GitHub, GitLab, most wikis and many note apps show as formatted text.

1. Give the files names that travel well

Names with spaces need quoting on the command line and turn into %20 in web addresses. If a project has them, paste the names, one per line, into Case & Style: File name: spaces to dashes (or to underscores) changes every name and leaves each extension alone, so Project Plan v2.docx becomes Project-Plan-v2.docx. File name: dashes and underscores to spaces goes the other way. Rename the files before drawing the tree, so it shows the names people will see.

2. Draw the folder structure

Open Folder Tree and choose the project’s folder, or drop it on the page. Only names and sizes are read, never what’s in the files. Keep Style on Lines for a tree like the tree command draws, set Levels to 2 or 3 so it shows the shape rather than every file, and check that Ignore lists anything that shouldn’t appear, such as node_modules or .git. Folders only gives an overview of a large project.

Paste the tree into the README inside a code block, between two lines of three backticks, so its lines stay lined up. Choose Markdown list instead if you’d rather have a plain bulleted list.

3. Draw how the pieces fit

A tree shows where files are, not how the parts work together. Open Mermaid Editor and choose a kind of diagram in Start from, such as a flowchart or a sequence diagram, then change its text to describe your project. The diagram redraws as you type, and the message line says which line is wrong if it can’t be read. Reference lists short examples for each kind of diagram, and Insert adds one where the cursor is. When it looks right, Copy as Markdown copies the text inside a code block marked mermaid, ready for the README: GitHub and GitLab draw it in place. Other wikis and note apps may show only the text, so look at it where it will be read. Save PNG or Save SVG gives a picture for those places.

4. Turn spreadsheets into tables

Settings, contacts, versions and steps often already live in a spreadsheet. Copy the cells and paste them into Markdown Table, then Make table and Copy the result. The first row becomes the header, and the columns are padded so the table is readable in plain text as well as on the page.

5. Make the links consistent

Collect the links the reader will need (the issue tracker, the design files, the server, the people to ask) as titles and addresses: two columns copied from a spreadsheet work, as do Title - https://… lines or bare addresses. Paste them into Link Formatter with Format set to Markdown, or to Markdown, reference style, which keeps long addresses out of the text by listing them at the end. The same list in HTML or Copy as rich text links suits an email or a document that isn’t Markdown.

6. Check and tidy the Markdown

Paste the whole README into Markdown Format. It lists mistakes by line, such as a link to a heading that doesn’t exist or a code block that’s never closed, and puts style right in Formatted: blank lines around headings, and one choice of Bullets, Italic and Bold markers. For a long README, put <!-- toc --> on a line of its own where the contents should go, and the formatted text gets a table of contents made from the headings. Copy Formatted back into the file, and look at it once on the site that will show it, as each shows Markdown a little differently.