Document npm packages using README files

Trevor Miller
InstructorTrevor Miller

Share this video with your friends

Send Tweet
Published 6 years ago
Updated 4 years ago

Users need to know how to use our package. We can make this easy for them with a file containing information about our project. We will put a simple example at the top for easy use.

[00:00] Let's create a file, which stands for Markdown. Let's open that file in our code editor. In a second pane, I've opened up my example use of the package that we can use to write our documentation.

[00:14] First, let's say this is an example. Let's make a code block here. Inside the code block, let's put a dollar sign, which is a common convention to let the user know this is a terminal command. We'll say mpm-install sensitive words with the save command so the user saves it to their package.json dependencies.

[00:35] Now that the user has the package installed, let's show an example of using it. Let's create another code block. Let's say const sensitive words=requiring in sensitive words. We can also include an ES2015 modules version. The user could say import sensitive words from sensitive words.

[01:00] To use this package, let's import it. I'm going to copy what we have in our test project so that it's filtered in console, and we'll paste it over here in our documentation. Underneath this console log, I found it helpful to include a comment of what we'll get output.

[01:16] I'm going to copy this string that was input and paste it here. I'm going to close my other tab. Because we're filtering out the words pro and touch bar here in our example, let's filter out the word pro and touch bar.

[01:32] The last thing is let's add syntax highlighting to this code block text. If we go up and right after this put JavaScript here, this lets the Markdown renderer know that this is a JavaScript example. Same thing for this one here. We can add shell here.

[01:51] Let's save and close this file. When we push our latest code, websites will render the ReadMe with the code blocks and our syntax highlighting.