• Nextra Demo
• Why? 🤷‍♀️
• What? ✨
• Who? 👥
• How? 👩‍💻
  • 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

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.

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.

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!

Ready? Let's go! 🚀

## Run the Finished Project

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

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

Run:

npm i

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>

Open your web browser in http:https://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 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

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

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

Thank you! 🙏

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!