How to create a README file on Mac
You can do this with Note My. Forty built-in templates cover the documents, licences and config files a project is expected to carry — here is where they live and what fills itself in.
You are starting a project and it needs the usual supporting files. A README. A licence. A .gitignore. Probably a CHANGELOG too. None of them are hard to write; all of them are tedious to find — so you end up pasting from an old repository or a web page, then editing out somebody else's name and last year's date.
Note My carries 40 built-in templates in four groups, plus a fifth group for templates you save yourself. This guide covers which files are in there, how to create one, what fills itself in on your behalf, and how to turn a README you are happy with into a template you can reach for again.
Every built-in template comes with the app. Nothing is downloaded and there is no account to create, so the catalogue behaves the same on a Mac that has never been online. It all happens on your Mac.
The eight project documents
The Documents group holds the files a repository is expected to carry, each already pointed at the filename convention expects it to have.
| Template | Becomes |
|---|---|
| README | README.md |
| CHANGELOG | CHANGELOG.md |
| CONTRIBUTING | CONTRIBUTING.md |
| CODE_OF_CONDUCT | CODE_OF_CONDUCT.md |
| SECURITY | SECURITY.md |
| Pull Request Template | PULL_REQUEST_TEMPLATE.md |
| Issue — Bug Report | bug_report.md |
| Issue — Feature Request | feature_request.md |
Each arrives as a new tab with the body already written and the parts you have to supply left clearly open. Nothing is on disk yet — the file exists when you save it, and not before.
If you write only one of them, write the README. The headings you are given are a sensible running order: what the project is, how to install it, how to run it, how to get in touch. Fill in the first two now; a short accurate README beats a long stale one.
Four licence texts, one filename
The Licenses group offers MIT, BSD 3-Clause, ISC and Apache 2.0. All four are meant to become the same file: LICENSE, no extension.
The Apache 2.0 entry gives you the standard notice, listed as such in the catalogue and ready to sit at the head of your project. Whichever of the four suits you, the wording arrives written, with the current year and your name already in the copyright line — so the decision is the only work left, and it is a decision about your project rather than about your editor.
When you save one, type the name as plain LICENSE with nothing after it. An added .txt is the usual reason a licence goes unnoticed.
Config files, from .gitignore to pyproject.toml
The Config group holds ten: .gitignore · .editorconfig · Dockerfile · Makefile · a GitHub Actions workflow saved as ci.yml · docker-compose.yml · .env.example · tsconfig.json · package.json · pyproject.toml.
A fourth group, Languages, holds 18 single-file starters — main.swift, main.py, index.html, script.sh and the rest — for when you need a file to start from rather than a document that explains.
Create the file and save it where it belongs
-
Open the Templates menu
Click Templates in the toolbar — the pull-down whose tooltip reads "New file from a template, save the current file as one, or insert a smart token". The same list is at File ▸ New from Template. The two show the same thing.
-
Pick the document you need
The menu is grouped: Documents, Licenses, Config, Languages, and My Templates for anything you have saved yourself. Choosing one opens a new tab containing the template body.
-
Fill in what was left for you
The caret is already waiting at the first thing you have to write. Work down from there, replacing the obvious placeholders: the project name, the description, the install command.
-
Save it with the conventional name
Press ⇧⌘S and give the file the name the table above lists —
README.md,LICENSE,.gitignore. New documents are written as UTF-8 with LF line endings by default, which is what every one of these files wants.You can write the whole thing before you decide where it lives. An untitled tab is looked after from the first keystroke by our auto-recovery safety net, so a half-written README is as safe before its first save as after it. Name it when you are ready.
-
Check it landed in the right folder
Press ⇧⌘R for File ▸ Reveal in Finder. ⌥⇧⌘C copies the full path if you want to paste it into a terminal.
The year and your name fill themselves in
Template bodies can carry smart tokens — 14 of them — and our template library fills them in for you. That is why a licence arrives with this year and your name in the copyright line rather than someone else's, and why the first thing you have to type is usually the project name.
| Token | Resolves to |
|---|---|
{{YEAR}} | The current four-digit year |
{{AUTHOR}} | Your name from Settings, or your macOS account's full name |
{{DATE}} · {{DATE_ISO}} | Today, long form or as YYYY-MM-DD |
{{FILENAME}} · {{FILEBASE}} | The file's name, with or without its extension |
{{UUID}} | A freshly generated lowercase UUID |
{{PROJECT}} | A project-name placeholder — you replace this one |
{{CURSOR}} | Nothing visible — it sets where the caret starts |
Be clear about the difference between the two kinds. Year, date, author, filename and UUID arrive as real values and can be left alone. {{PROJECT}} is the one nobody can answer for you — the catalogue lists it as a project-name placeholder, so treat it as something you fill in yourself.
You can drop tokens into anything you are writing, not only templates, from Templates ▸ Insert Smart Token. Each value token has two entries: the plain one puts in the finished value, and holding ⌥ puts in the literal {{TOKEN}} instead — useful when you are writing a template rather than using one. Expand Smart Tokens in Document then fills in every literal token across the whole document in one go.
Two rules worth knowing. Writing \{{X}} keeps a token as text, and the backslash does not survive into the file. And an unknown token is left exactly as you typed it rather than blanked — a stray {{FOO}} stays where you can see it and fix it.
Setting your author name once
Open Settings with ⌘, and go to the Editing pane. The name you set there is what {{AUTHOR}} uses from then on. Leave it empty and you get your macOS account's full name, which is often already the one you want. If the label is hard to spot, type into the sidebar's search field — it looks across every setting in all 14 panes. Do it once, and every copyright line afterwards names you.
Files named rather than extended
Dockerfile, Makefile, .env.example and the other dot-files in the Config group carry no file extension at all. Our advanced language identifier still settles them on Plain Text, which is the right home for a build file and needs nothing from you — the file opens ready to edit and you can get straight on with it.
Plain Text is safer than the name suggests. You still get macOS's own spelling and grammar underlines, so prose in a README is checked as you write it. What you never get, here or anywhere else in the app, is anything that rewrites your text: no auto-correct, no smart quotes, no dash substitution, no link or data detection. A Dockerfile cannot pick up a curly apostrophe while you are not looking.
To see which language a file is set to, click the Identify pill in the status bar. The Language Inspector names it and lets you change it — useful for a config file with an unusual name.
Making the same files from the Finder
You do not have to be in the app to start one. With the Finder extension enabled, right-clicking gives you a Note My ▸ submenu.
- Right-click a file and you get New File Beside This… ▸, which creates the new document in the same folder — the usual case when you are adding a README next to code that already exists.
- Right-click a folder, or its background, and you get New File Here… ▸, plus New File from Clipboard if what you want is already copied.
Turn the extension on from page 8 of onboarding, or later in System Settings. From then on each of those submenus carries its own quick list of starting points — Empty File… at the top, then a grouped list of templates — so a README can be started in the folder it belongs to, wherever in the Finder you happen to be standing. The file appears in the folder and Note My comes forward with it already open in a tab, ready to type into, so adding a README to a folder full of code is a right-click and a sentence. When you want the whole set of forty, together with anything you have saved under My Templates, that is what the Templates pull-down and File ▸ New from Template are for.
Turn your own README into a template
The four built-in groups are a starting point rather than the whole story. Once you have a README you actually like — your headings, your tone, your badge row, the contact line you always write — Save Current Document as Template… in the same menu keeps it. It joins a fifth group, My Templates, and from then on it sits alongside the built-ins and opens a new tab in exactly the same way.
This is where smart tokens earn their keep. Write your own template with the literal tokens in it — hold ⌥ as you insert one and you get {{AUTHOR}} on the page rather than your name — and every document you make from it afterwards arrives with this year, today's date and your name already correct. A house licence header, a CHANGELOG in your own version-heading style, an issue template that asks the questions your projects actually need: each becomes a single menu item, and each fills itself in.
Templates are whole documents, and that is what makes them worth keeping. What you save is the finished shape of a README rather than a fragment to be assembled later, so what opens is already in a state you would be content to commit, and the only thing left to write is the part that changes from project to project.
To tidy the group later, hold ⌥ while the Templates menu is open and each of your own entries becomes Delete "<name>". The same key, the same menu, doing the obvious thing in both places.
Troubleshooting
My licence ended up as LICENSE.txt
Convention wants the file called LICENSE, with nothing after the name, and an added extension is the usual reason one goes unnoticed by the tools that look for it. In the save sheet, type the name exactly as you want it — no dot, no extension — and confirm it as typed when macOS asks whether to add one. If a file has already been written the long way, rename it in the Finder, then press ⇧⌘R from the tab to confirm the right file is sitting in the right folder. The same applies to Dockerfile, Makefile and the dot-files in the Config group.
The tokens are still showing as {{AUTHOR}} and {{YEAR}}
Two likely causes. You used the ⌥ alternate, which deliberately puts the literal token in. Or the text arrived by paste rather than through the template. Either way, Templates ▸ Expand Smart Tokens in Document fills them all in across the whole document in one go.
The author name is wrong or empty
Set it in Settings ▸ Editing. That corrects everything you make from then on. A file you have already created keeps the name it was given — fix that one by editing the line yourself, or by putting the literal token back in with ⌥ and running Expand Smart Tokens over it.
A file made from the Finder is not where I expected
New files land in the folder you right-clicked whenever that folder can be written to. Where it cannot — a locked folder, or one you do not own — you still get your document, but not where you expected. Check the folder's permissions, then save it again from the app with ⇧⌘S.
Text pasted from an AI chat carries invisible characters
Common in a README assembled from a chat window. Use Clean ▸ Clean AI Copy/Paste Markers — one click, no dialog. Our hidden-character scanner takes out only the invisible leftovers that cannot change your wording, punctuation, indentation or emoji, and tells you about anything riskier instead of acting on it. You will see either "No hidden copy/paste markers found." or a count of what was cleaned, along with the reassurance that your text itself was not rewritten.
Trailing spaces keep getting flagged in Markdown
They should not be. Our cleanup rules treat Markdown on its own terms: two trailing spaces there are a deliberate hard line break, not a mistake, so they are left alone. You can tidy a README without losing the line breaks you meant to keep.
Frequently asked questions
Where exactly are the templates?
Two places, both showing the same list: the Templates pull-down in the toolbar, and File ▸ New from Template. Use whichever is nearer to hand; there is no difference between them.
Can I save my own README as a template?
Yes. Save Current Document as Template… in the same menu adds it to a fifth group called My Templates. To remove one later, hold ⌥ while the menu is open and the entry becomes Delete "<name>".
Which licence template should I pick?
All four are waiting for you: MIT, BSD 3-Clause, ISC and the Apache 2.0 notice, each arriving with the current year and your name already in the copyright line, and each meant to be saved as a file named LICENSE. Read the terms, pick the one that suits the project, and the wording is already written.
What happens to the year in a LICENSE I saved last year?
It stays exactly as you wrote it. The year lands as ordinary text at the moment the file is created, and from then on it is yours to edit like any other word — nothing in a saved file changes on its own, which is precisely what you want from a licence. Every new licence you create picks up the current year as it opens, so the only ones worth a glance each January are the older files you are carrying forward.
What encoding and line endings do new files get?
UTF-8 and LF, by default, for every new document — the pair these project files expect. Both are changeable per file from the File menu or the status-bar pills, and our encoding handling offers 18 encodings and three line-ending styles if you need something else.
Does creating these files need an internet connection?
You can create every one of them on a Mac that has never been online. All 40 templates come with the app, nothing is downloaded, and there is no account to sign into. Your files never leave your Mac.