├── .editorconfig
├── .gitattributes
├── .github
└── workflows
│ └── ci.yaml
├── .gitignore
├── .nvmrc
├── .prettierignore
├── .tool-versions
├── .yarn
└── releases
│ └── yarn-4.0.2.cjs
├── .yarnrc.yml
├── LICENSE
├── README.md
├── components
├── SyntaxHighlighter.tsx
└── Template.tsx
├── dev
├── global.css
├── lighthouserc.js
├── netlify.toml
├── next-env.d.ts
├── next.config.js
├── package.json
├── pages
├── _app.tsx
├── _document.tsx
└── index.tsx
├── postcss.config.js
├── public
└── images
│ ├── favicon.ico
│ └── open-graph-logo.png
├── tailwind.config.js
├── tsconfig.json
└── yarn.lock
/.editorconfig:
--------------------------------------------------------------------------------
1 | # editorconfig.org
2 | root = true
3 |
4 | [*]
5 | charset = utf-8
6 | end_of_line = lf
7 | indent_size = 4
8 | indent_style = space
9 | insert_final_newline = true
10 | trim_trailing_whitespace = true
11 |
--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
1 | # Handle line endings in Git
2 | * text=auto
3 | *.ico binary
4 | *.png binary
5 |
6 | # https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored
7 | /.yarn/releases/** binary
8 | /.yarn/plugins/** binary
9 |
--------------------------------------------------------------------------------
/.github/workflows/ci.yaml:
--------------------------------------------------------------------------------
1 | name: CI
2 |
3 | on:
4 | push:
5 | branches:
6 | - main
7 | pull_request:
8 |
9 | jobs:
10 | build:
11 | runs-on: ubuntu-latest
12 |
13 | steps:
14 | - uses: actions/checkout@v4
15 | - uses: actions/setup-node@v4
16 | with:
17 | node-version-file: ".tool-versions"
18 | - name: Get the Yarn cache directory path
19 | id: yarn-cache-dir-path
20 | run: echo "dir=$(yarn config get cacheFolder)" >> $GITHUB_OUTPUT
21 | - uses: actions/cache@v4
22 | with:
23 | path: ${{ steps.yarn-cache-dir-path.outputs.dir }}
24 | key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
25 | restore-keys: |
26 | ${{ runner.os }}-yarn-
27 | - name: Install packages
28 | run: yarn install --immutable
29 | - name: Check formatting
30 | run: yarn run format:check
31 | # - name: Lint the code
32 | # run: yarn run lint
33 | - name: Build the website
34 | run: yarn run build
35 | - name: Run Lighthouse
36 | run: npx --package=@lhci/cli lhci autorun
37 | env:
38 | LHCI_GITHUB_APP_TOKEN: ${{ secrets.LHCI_GITHUB_APP_TOKEN }}
39 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | *.swp
2 | *.swo
3 | .DS_Store
4 | .next/
5 | build/
6 | node_modules/
7 |
8 | # Yarn
9 | # https://yarnpkg.com/getting-started/qa#which-files-should-be-gitignored
10 | .pnp.*
11 | .yarn/*
12 | !.yarn/patches
13 | !.yarn/plugins
14 | !.yarn/releases
15 | !.yarn/sdks
16 | !.yarn/versions
17 |
--------------------------------------------------------------------------------
/.nvmrc:
--------------------------------------------------------------------------------
1 | 20.11.1
2 |
--------------------------------------------------------------------------------
/.prettierignore:
--------------------------------------------------------------------------------
1 | *.md
2 | .next/
3 | .yarn/
4 | build/
5 |
--------------------------------------------------------------------------------
/.tool-versions:
--------------------------------------------------------------------------------
1 | nodejs 20.11.1
2 |
--------------------------------------------------------------------------------
/.yarnrc.yml:
--------------------------------------------------------------------------------
1 | compressionLevel: mixed
2 |
3 | defaultSemverRangePrefix: ""
4 |
5 | enableGlobalCache: false
6 |
7 | nodeLinker: node-modules
8 |
9 | yarnPath: .yarn/releases/yarn-4.0.2.cjs
10 |
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2017 Danny Guo
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # Make a README
2 |
3 | [](https://app.netlify.com/sites/make-a-readme/deploys)
4 | [](https://github.com/dguo/make-a-readme/actions?query=branch%3Amain)
5 |
6 | [Make a README](https://makeareadme.com) explains what a README is, what the
7 | benefits are, and what makes for a good README. It also provides an editable
8 | template, with live Markdown rendering.
9 |
10 | I hope people who are new to programming will find it useful, but even for
11 | more experienced programmers, I think it's worth evaluating once
12 | in a while if we are doing a good job when it comes to the
13 | [small details](https://chris.beams.io/posts/git-commit/) that
14 | can matter more than we might think.
15 |
16 | Make a README is inspired by [Keep a Changelog](http://keepachangelog.com/).
17 |
18 | ## Related Resources
19 |
20 | - [Art of README](https://github.com/noffle/art-of-readme)
21 | - [Awesome README](https://github.com/matiassingers/awesome-readme)
22 | - [Standard Readme](https://github.com/RichardLitt/standard-readme)
23 |
24 | ## Roadmap
25 |
26 | - Translate the website
27 | - Create an interactive README generator ([#15](https://github.com/dguo/make-a-readme/issues/15))
28 | - Link to great examples ([#14](https://github.com/dguo/make-a-readme/issues/14))
29 | - check and improve accessibility
30 |
31 | ## Contributing
32 |
33 | Please feel free to submit an issue or pull request. To develop, you'll need
34 | Node.js. Run `yarn install && yarn dev`.
35 |
36 | ## License
37 |
38 | [MIT](https://github.com/dguo/make-a-readme/blob/main/LICENSE)
39 |
--------------------------------------------------------------------------------
/components/SyntaxHighlighter.tsx:
--------------------------------------------------------------------------------
1 | import {LightAsync} from "react-syntax-highlighter";
2 | import {a11yDark} from "react-syntax-highlighter/dist/cjs/styles/hljs";
3 |
4 | function SyntaxHighlighter(props) {
5 | const {children, className} = props;
6 | if (!children) {
7 | return null;
8 | }
9 |
10 | // An example className is "language-python"
11 | const languageMatch = /language-(\w+)/.exec(className || "");
12 |
13 | /* This is a simplified version of the example from the react-markdown docs:
14 | https://github.com/remarkjs/react-markdown?tab=readme-ov-file#use-custom-components-syntax-highlight
15 |
16 | If we have a language, we render it as a code block with syntax
17 | highlighting. Otherwise, we render an inline code element.
18 |
19 | One issue is that this approach doesn't handle a code block that doesn't
20 | have a language identifier, though GitHub supports that:
21 | https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks#fenced-code-blocks
22 |
23 | It is rendered as an inline code element instead of a code block. See
24 | this issue for more context:
25 | https://github.com/remarkjs/react-markdown/issues/776
26 |
27 | If we could distinguish between inline code and code blocks, we could
28 | still use the syntax highlighter and pass in plain text for the language.
29 | Instead, our hacky fix for this is to apply CSS by targeting the
30 | language-less code blocks and copying over the styling that is provided
31 | by github-markdown-css. See the ".markdown-body pre > code" selector in
32 | global.css.
33 | */
34 | return languageMatch ? (
35 |
54 |
57 |
69 | Rendered
70 |
43 | );
44 | }
45 |
46 | export default SyntaxHighlighter;
47 |
--------------------------------------------------------------------------------
/components/Template.tsx:
--------------------------------------------------------------------------------
1 | import {useState} from "react";
2 | import ReactMarkdown from "react-markdown";
3 | import TextareaAutosize from "react-textarea-autosize";
4 | import SyntaxHighlighter from "./SyntaxHighlighter";
5 |
6 | const INITIAL_TEMPLATE = `# Foobar
7 |
8 | Foobar is a Python library for dealing with word pluralization.
9 |
10 | ## Installation
11 |
12 | Use the package manager [pip](https://pip.pypa.io/en/stable/) to install foobar.
13 |
14 | \`\`\`bash
15 | pip install foobar
16 | \`\`\`
17 |
18 | ## Usage
19 |
20 | \`\`\`python
21 | import foobar
22 |
23 | # returns 'words'
24 | foobar.pluralize('word')
25 |
26 | # returns 'geese'
27 | foobar.pluralize('goose')
28 |
29 | # returns 'phenomenon'
30 | foobar.singularize('phenomena')
31 | \`\`\`
32 |
33 | ## Contributing
34 |
35 | Pull requests are welcome. For major changes, please open an issue first
36 | to discuss what you would like to change.
37 |
38 | Please make sure to update tests as appropriate.
39 |
40 | ## License
41 |
42 | [MIT](https://choosealicense.com/licenses/mit/)`;
43 |
44 | export function Template() {
45 | const [template, setTemplate] = useState(INITIAL_TEMPLATE);
46 |
47 | return (
48 |
Template
50 |
51 |
125 | Because no one can read your mind ( 126 | 127 | yet 128 | 129 | ) 130 |
131 |144 | A{" "} 145 | 146 | README 147 | {" "} 148 | is a text file that introduces and explains a project. 149 | It contains information that is commonly required to 150 | understand what the project is about. 151 |
152 |156 | It's an easy way to answer questions that your audience 157 | will likely have regarding how to install and use your 158 | project and also how to collaborate with you. 159 |
160 |164 | Anyone who is working on a programming project, 165 | especially if you want others to use it or contribute. 166 |
167 |171 | Definitely before you show a project to other people or 172 | make it public. You might want to get into the habit of 173 | making it the{" "} 174 | 175 | first file you create 176 | {" "} 177 | in a new project. 178 |
179 |183 | In the top level directory of the project. This is where 184 | someone who is new to your project will start out. Code 185 | hosting services such as{" "} 186 | GitHub,{" "} 187 | Bitbucket, and{" "} 188 | GitLab will also 189 | look for your README and display it along with the list 190 | of files and directories in your project. 191 |
192 |196 | While READMEs can be written in any text file format, 197 | the most common one that is used nowadays is{" "} 198 | 199 | Markdown 200 | 201 | . It allows you to add some lightweight formatting. You 202 | can learn more about it at the{" "} 203 | CommonMark website 204 | , which also has a helpful{" "} 205 | 206 | reference guide 207 | {" "} 208 | and an{" "} 209 | 210 | interactive tutorial 211 | 212 | . 213 |
214 |215 | Some other formats that you might see are{" "} 216 | 217 | plain text 218 | 219 | ,{" "} 220 | 221 | reStructuredText 222 | {" "} 223 | (common in Python{" "} 224 | projects), and{" "} 225 | 226 | Textile 227 | 228 | . 229 |
230 |231 | You can use any text editor. There are plugins for many 232 | editors (e.g.{" "} 233 | 234 | Atom 235 | 236 | ,{" "} 237 | 238 | Emacs 239 | 240 | ,{" "} 241 | 242 | Sublime Text 243 | 244 | ,{" "} 245 | 246 | Vim 247 | 248 | , and{" "} 249 | 250 | Visual Studio Code 251 | 252 | ) that allow you to preview Markdown while you are 253 | editing it. 254 |
255 |256 | You can also use a dedicated Markdown editor like{" "} 257 | Typora or an online one 258 | like StackEdit or{" "} 259 | Dillinger. You can 260 | even use the editable template below. 261 |
262 |269 | Every project is different, so consider which of these 270 | sections apply to yours. The sections used in the template 271 | are suggestions for most open source projects. Also keep in 272 | mind that while a README can be too long and detailed, too 273 | long is better than too short. If you think your README is 274 | too long, consider utilizing{" "} 275 | 276 | another form of documentation 277 | {" "} 278 | rather than cutting out information. 279 |
280 | 281 |Choose a self-explaining name for your project.
283 |287 | Let people know what your project can do specifically. 288 | Provide context and add a link to any reference visitors 289 | might be unfamiliar with. A list of Features or a{" "} 290 | Background subsection can also be added here. If 291 | there are alternatives to your project, this is a good 292 | place to list differentiating factors. 293 |
294 |298 | On some READMEs, you may see small images that convey 299 | metadata, such as whether or not all the tests are 300 | passing for the project. You can use{" "} 301 | Shields to add some to 302 | your README. Many services also have instructions for 303 | adding a badge. 304 |
305 |309 | Depending on what you are making, it can be a good idea 310 | to include screenshots or even a video (you'll 311 | frequently see GIFs rather than actual videos). Tools 312 | like{" "} 313 | ttygif{" "} 314 | can help, but check out{" "} 315 | Asciinema for a 316 | more sophisticated method. 317 |
318 |322 | Within a particular ecosystem, there may be a common way 323 | of installing things, such as using{" "} 324 | Yarn,{" "} 325 | NuGet, or{" "} 326 | Homebrew. However, 327 | consider the possibility that whoever is reading your 328 | README is a novice and would like more guidance. Listing 329 | specific steps helps remove ambiguity and gets people to 330 | using your project as quickly as possible. If it only 331 | runs in a specific context like a particular programming 332 | language version or operating system or has dependencies 333 | that have to be installed manually, also add a{" "} 334 | Requirements subsection. 335 |
336 |340 | Use examples liberally, and show the expected output if 341 | you can. It's helpful to have inline the smallest 342 | example of usage that you can demonstrate, while 343 | providing links to more sophisticated examples if they 344 | are too long to reasonably include in the README. 345 |
346 |350 | Tell people where they can go to for help. It can be any 351 | combination of an issue tracker, a chat room, an email 352 | address, etc. 353 |
354 |358 | If you have ideas for releases in the future, it is a 359 | good idea to list them in the README. 360 |
361 |365 | State if you are open to contributions and what your 366 | requirements are for accepting them. 367 |
368 |369 | For people who want to make changes to your project, 370 | it's helpful to have some documentation on how to get 371 | started. Perhaps there is a script that they should run 372 | or some environment variables that they need to set. 373 | Make these steps explicit. These instructions could also 374 | be useful to your future self. 375 |
376 |377 | You can also document commands to{" "} 378 | 379 | lint the code 380 | {" "} 381 | or{" "} 382 | 383 | run tests 384 | 385 | . These steps help to ensure high code quality and 386 | reduce the likelihood that the changes inadvertently 387 | break something. Having instructions for running tests 388 | is especially helpful if it requires external setup, 389 | such as starting a{" "} 390 | Selenium server 391 | for testing in a browser. 392 |
393 |397 | Show your appreciation to those who have contributed to 398 | the project. 399 |
400 |404 | For open source projects, say how it is{" "} 405 | licensed. 406 |
407 |411 | If you have run out of energy or time for your project, 412 | put a note at the top of the README saying that 413 | development has slowed down or stopped completely. 414 | Someone may choose to fork your project or volunteer to 415 | step in as a maintainer or owner, allowing your project 416 | to keep going. You can also make an explicit request for 417 | maintainers. 418 |
419 |434 | Not all of the suggestions here will make sense for 435 | every project, so it's really up to the developers 436 | what information should be included in the README. 437 |
438 |445 | Check out{" "} 446 | 447 | Awesome README 448 | {" "} 449 | for a list of more resources. 450 |
451 |
458 | README.md
(or a different file
459 | extension if you choose to use a non-Markdown file
460 | format). It is{" "}
461 |
462 | traditionally uppercase
463 | {" "}
464 | so that it is more prominent, but it's not a big
465 | deal if you think it{" "}
466 |
467 | looks better lowercase
468 |
469 | .
470 |
478 | Please don't hesitate to open an{" "} 479 | 480 | issue 481 | {" "} 482 | or{" "} 483 | 484 | pull request 485 | 486 | . You can also send me a message on{" "} 487 | Twitter. 488 |
489 |493 | 494 | Scientists 495 | {" "} 496 | and companies like{" "} 497 | 498 | Facebook 499 | {" "} 500 | and{" "} 501 | Neuralink{" "} 502 | (presumably) are working on it. Perhaps in the 503 | future, you'll be able to attach a copy of your 504 | thoughts and/or consciousness to your projects. In 505 | the meantime, please make READMEs. 506 |
507 |514 | A README is a crucial but basic way of documenting your 515 | project. While every project should at least have a 516 | README, more involved ones can also benefit from a{" "} 517 | wiki or 518 | a dedicated documentation website.{" "} 519 | 520 | GitHub 521 | 522 | ,{" "} 523 | 524 | Bitbucket 525 | 526 | , and{" "} 527 | 528 | GitLab 529 | {" "} 530 | all support maintaining a wiki alongside your project, 531 | and here are some tools and services that can help you 532 | generate a documentation website: 533 |
534 |561 | And to learn more about technical documentation in 562 | general, consider reading these books (I may earn 563 | commissions if you buy through these links): 564 |
565 |595 | If your project is{" "} 596 | 597 | open source 598 | 599 | , it's{" "} 600 | 601 | important 602 | {" "} 603 | to include a{" "} 604 | 605 | license 606 | 607 | . You can use{" "} 608 | this website{" "} 609 | to help you pick one. 610 |
611 |615 | Make a README is inspired by{" "} 616 | 617 | Keep a Changelog 618 | 619 | . A{" "} 620 | 621 | changelog 622 | {" "} 623 | is another file that is very useful for programming 624 | projects. 625 |
626 |
630 | Just having a "Contributing" section in your README is a
631 | good start. Another approach is to split off your
632 | guidelines into their own file (
633 | CONTRIBUTING.md
). If you use GitHub and
634 | have this file, then anyone who creates an issue or
635 | opens a pull request{" "}
636 |
637 | will get a link
638 | {" "}
639 | to it.
640 |
642 | You can also create an{" "} 643 | 644 | issue template 645 | {" "} 646 | and a{" "} 647 | 648 | pull request template 649 | 650 | . These files give your users and collaborators 651 | templates to fill in with the information that you'll 652 | need to properly respond. This helps to avoid situations 653 | like getting very vague issues. Both GitHub and{" "} 654 | 655 | GitLab 656 | {" "} 657 | will use the templates automatically. 658 |
659 |