Scribd
Upload
5 views

Nextra Guide CODING75 - Copy

This document is a comprehensive guide for using the Nextra Docs Template with Next.js to create a documentation site using MDX. It covers topics such as routing and file organization, writing MDX content, converting PDF content to MDX, code maintenance, and the pull request process. Additional resources for further reading are also provided to enhance understanding of the tools and practices involved.

Uploaded by

Gaurav Sharma
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
5 views

Nextra Guide CODING75 - Copy

This document is a comprehensive guide for using the Nextra Docs Template with Next.js to create a documentation site using MDX. It covers topics such as routing and file organization, writing MDX content, converting PDF content to MDX, code maintenance, and the pull request process. Additional resources for further reading are also provided to enhance understanding of the tools and practices involved.

Uploaded by

Gaurav Sharma
Copyright
© © All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
You are on page 1/ 7

Comprehensive Guide to the Nextra Docs

Template
1. Overview
This project is built on Next.js with the Nextra Docs Template to create a documentation (or
notes) site using MDX (Markdown with JSX). The project leverages file-based routing, which
means that pages are defined by their location and name in the file structure. This guide will
help you understand:

Routing & File Organization: How Next.js uses files and folders to create routes.
MDX: How to write content that combines Markdown with React components.
Converting PDF Content to MDX: How to use ChatGPT and UI tools to parse PDF content
into MDX.
Code Maintenance & PR Process: How to work with the codebase and contribute
changes using pull requests.

2. Project Structure & Routing


2.1 File-Based Routing in Next.js
Next.js uses a file-based routing system. Here’s what you need to know:

Pages Directory: Any file you add in the pages folder becomes a route.
For example, pages/about.js is accessible at https://your-site.com/about .
Nested Folders: You can create nested routes by placing files in subdirectories.
Example: pages/docs/intro.mdx is accessible at https://your-
site.com/docs/intro .
Dynamic Routes: Files named with square brackets (e.g., [id].js ) create dynamic
routes.

2.2 Nextra-Specific File Structure


While the Nextra Docs Template follows many Next.js conventions, note these specifics:

Content Folder: Many documentation sites built with Nextra have a dedicated folder
(commonly named docs or within pages ) where all MDX files live.
Navigation Configuration: Some projects use a configuration file (e.g., theme.config.js
or similar) to define sidebar navigation or custom routes. Check the project root for such
files.

2.3 Adding New Pages


To add a new page or section:

1. Create an MDX File:


Place a new .mdx file in the appropriate folder. For example, to add a "Getting Started"
page, create pages/getting-started.mdx .
2. Update Navigation (if needed):
If the template uses a navigation config file, add an entry for the new page to ensure it
shows up in the sidebar or menu.
3. Linking Between Pages:
Use standard Markdown links or Next.js’s <Link> component (when using JSX in your
MDX) to interconnect pages.

Example Markdown Link:

[Go to Getting Started](/getting-started)

3. Working with MDX


3.1 What is MDX?
MDX is a blend of Markdown and JSX. It allows you to write Markdown for most content while
embedding React components for interactive or dynamic features.

3.2 Writing MDX Content


Basic Markdown:
Write text, headings, lists, images, etc., just like in any Markdown file.
Embedding Components:
You can import and use React components directly in your MDX files.
Example MDX File ( example.mdx ):

import CustomAlert from '../components/CustomAlert';

# Welcome to Our Docs

This is an example of a **Markdown** page with an embedded React component.

<CustomAlert type="info">
Remember to check the documentation regularly!
</CustomAlert>

3.3 Tips for MDX


Component Imports:
Import any components at the top of the file before using them.
Syntax Highlighting:
Use triple backticks (```) to denote code blocks and specify the language for proper syntax
highlighting.
Resources:
MDX Documentation
Next.js MDX Integration Guide

3.4 Converting PDF Content to MDX Using ChatGPT and UI


Tools
Sometimes, you may have content available in PDF format that needs to be integrated into your
documentation. Follow these steps to convert PDF content into MDX using ChatGPT and UI
tools:

4. Extract Text from the PDF:


UI Tools: Use applications like Adobe Acrobat or online PDF-to-text converters.
Command-line Tools: Tools like pdftotext can extract the text from your PDF.
Example (using pdftotext ):

pdftotext input.pdf output.txt

5. Prepare the Extracted Text for Conversion:


Review the extracted text for any formatting issues.
Remove any extraneous content that you do not want in your documentation.
6. Use ChatGPT to Convert Text to MDX:
Interactive Use:
Paste the cleaned text into ChatGPT with a clear prompt. For example:

"Please convert the following PDF text into a well-structured MDX document with
proper Markdown formatting, headings, and code blocks if applicable:"

API Integration:
If automating the process, you can use the ChatGPT API to programmatically convert
text into MDX. Create a script that sends the extracted text and retrieves the formatted
MDX output.
Review the Output:
ChatGPT’s output may need some adjustments. Verify that the headings, lists, links,
and any embedded components are correctly formatted.
7. Incorporate the MDX File into Your Project:
Save the output as an .mdx file in the appropriate directory (e.g., pages or docs ).
Integrate any necessary React component imports manually if the conversion did not
include them.
8. UI Tools for Refinement:
Use a Markdown/MDX editor (such as VSCode with MDX support) to further refine and
preview your content.
Tools like StackEdit or Typora can help visualize Markdown content and make additional
edits.

4. Codebase Maintenance
4.1 General Best Practices
Consistent Naming:
Stick to a naming convention for files and components to keep the codebase organized.
Documentation:
Comment your code and update documentation when making significant changes.
Testing:
Test your changes locally before pushing them. Run the development server with:

npm run dev

or
yarn dev

4.2 Branching and Version Control


Branching Strategy:
Work on feature branches instead of committing directly to main or master .
Commit Messages:
Write clear, concise commit messages that describe the change. For example:

feat: add new documentation page for installation


fix: correct typo in sidebar navigation

Code Reviews:
Ensure that your PRs are reviewed by a team member before merging.

5. Creating a Pull Request (PR)


5.1 Steps to Create a PR
9. Fork/Clone the Repository:
Clone the repository to your local machine if you haven’t already:

git clone https://github.com/your-org/your-repo.git

10. Create a New Branch:


Create a branch with a descriptive name:

git checkout -b feature/add-new-doc-page

11. Make Your Changes:


Edit files or add new files as needed. Save your changes.
12. Commit Your Changes:
Stage your changes and commit with a clear message:
git add .
git commit -m "feat: add new documentation page for installation"

13. Push Your Branch:


Push your branch to the remote repository:

git push origin feature/add-new-doc-page

14. Open a PR:


Navigate to your repository on GitHub.
You should see a prompt to compare & create a pull request for your newly pushed
branch. Click it.
Fill in the PR template (if available), detailing what changes were made and why.
Request reviews from your team members.

5.2 PR Best Practices


Describe Your Changes:
Provide context in your PR description so reviewers understand the purpose and scope.
Link Related Issues:
If the PR addresses an issue, reference it in the description (e.g., Closes #23 ).
Keep PRs Focused:
Aim for small, focused PRs on a single feature or fix to simplify reviews.

6. Additional Resources
Here are some useful resources for further reading and understanding:

Next.js Documentation:
https://nextjs.org/docs
MDX Documentation:
https://mdxjs.com/
Nextra Documentation:
(Check the GitHub repo’s README and Wiki if available)
ChatGPT & OpenAI Documentation:
OpenAI API Documentation
PDF-to-Text Tools:
pdftotext (Xpdf)
Git & GitHub Guides:
Git Documentation
GitHub Guides
Code Style and Best Practices:
Airbnb’s JavaScript Style Guide
How to Write a Git Commit Message

7. Summary
Routing & Files:
Use the pages folder to create routes.
Organize content in subfolders for a clear structure.
MDX:
Write Markdown with the ability to include React components.
Import components at the top of your MDX files.
Converting PDF to MDX:
Extract PDF text using UI or command-line tools.
Use ChatGPT (via the web interface or API) to convert text into structured MDX.
Refine the output using your preferred Markdown/MDX editor.
Code Maintenance:
Follow consistent naming, branch naming, and commit message practices.
Test locally and use code reviews.
PR Process:
Create feature branches, commit changes, and open a PR for review.
Use clear descriptions and reference related issues.

It's pretty simple, also try nextJS docs if you encounter something, your main focus is creating

PDF to MDX (and not much of technical aspects).

You might also like