Nextra Demo

A comprehensive demo / tutorial using Nextra for a documentation site
with authentication (private pages), search and analytics!

• Nextra Demo
• Why? 🤷‍♀️
• What? ✨
• Who? 👥
• How? 👩‍💻
  • Run the Finished Project
    • 1. Clone the Project
    • 2. Install Dependencies
    • 3. Create Environment Variables
    • 4. Run the App!
  • Run the Tests!
  • Build It!
• Please star the repo! ⭐️
• Troubleshooting
  • I'm getting an error pertaining a missing secret

Why? 🤷‍♀️

Working as a software engineer, you come across technical documentation daily. From API references to internal manuals, technical documentation is vital for the development process. Everyone expects docs as a hygiene factor. Without docs, knowledge of the application becomes siloed and means you cannot scale your team or continue in the event of someone leaving!

Great docs ensure long-term sustainability of your software projects. Having a clear record of the why, how and what helps maintain consistency and increases the quality of your work!

Whether it is meant as an internal reference or you're creating documentation for public-facing clients that are using your project, having documentation benefits both the developers and users alike.

What? ✨

Nextra is a framework that makes it easy for you to create a documentation static website fully optimized and powered by Next.js.

It simpifies the process of creating and maintaining documentation by offering a myriad of features, such as:

• Themeable design system.
• Markdown and MDX support.
• Full-text search out-of-the-box.
• Automatic a11y.
• Filesystem-based organization.

The integration with Next.js makes Nextra fully customizable, thus ideal for your team to quickly generate a website that is useful for both internal and external stakeholders.

Who? 👥

This walkthrough is meant for beginners and seasoned software engineers alike who want to create internal and external documentation for their teams.

This will not be an introduction to technical writing, it will solely focus on the Nextra framework. We recommend visiting developers.google.com/tech-writing if you are interested in learning more about technical writing.

If you find it useful, please give the repo a star! ⭐️

If you get stuck, have questions/suggestions or just want to discuss this further, please open an issue!

How? 👩‍💻

Ready? Let's go! 🚀

Run the Finished Project

1. Clone the Project

In your terminal, run the following command to clone the repo:

git clone [email protected]:dwyl/nextra-demo.git && cd nextra-demo

2. Install Dependencies

Run:

npm i

3. Create Environment Variables

Copy the .env.local-example file and create your .env.local file:

cp .env.local-example .env.local

Add the necessary environment variables to your .env.local file, e.g:

AUTH_SECRET=<YOUR_GENERATED_SECRET>

AUTH_GITHUB_ID=<GITHUB_OAUTH_APPLICATION_ID>
AUTH_GITHUB_SECRET=<GITHUB_OAUTH_APPLICATION_SECRET>

TEST_PASSWORD=<ANY_PASSWORD_FOR_TESTS_TO_RUN>

Note

Check tutorial.md to learn where to get these environment variables.

4. Run the App!

Open your web browser in http://localhost:3000 and run in dev mode by typing this in the terminal.

npm run dev

If you wish to run in production mode, make sure to run the build script first and then start.

npm run build
npm start

Run the Tests!

Run the tests with the following command:

npm run test

Alternatively, you can run end-to-end tests (which use Playwright) by running the following command:

npm run e2e:test

Build It!

Ready to build it yourself?! See: tutorial.md

Please star the repo! ⭐️

If you find this repo/tutorial useful, please star it on GitHub, so that we know! ⭐

Thank you! 🙏

Troubleshooting

I'm getting an error pertaining a missing secret

You may have encountered the following error.

[auth][error] MissingSecret: Please define a `secret`.. 
  Read more at https://errors.authjs.dev#missingsecret

It means that you're missing a secret from auth.js. Visit https://authjs.dev/reference/core/errors#missingsecret and create a secret and place it in the .env file locally and you should be good to go!