Nextra le permite crear un sitio en minutos, por lo que es perfecto para distribuir documentos a su equipo.
Si está familiarizado con Next.js, puede usarlo para desarrollar un sitio de documentación con facilidad. El marco Nextra se encarga de los detalles esenciales por usted; todo lo que tiene que hacer es agregar contenido Markdown o HTML y datos YAML o JSON.
Siga estos pasos para crear un sitio de documentación con Nextra, un generador de sitios estáticos basado en Next.js. Instalará y configurará las dependencias necesarias, luego aprenderá a agregar nuevos documentos y páginas, escribir Markdown e incluir componentes de React.
Requisitos para crear un sitio de documentos con Nextra
Comience instalando Node.js si aún no lo ha hecho. El última versión de Node.js viene con npm, el administrador de paquetes de nodos, que necesitará para instalar dependencias para este proyecto.
Además de Node.js, deberá instalar Git. Necesita Git para implementar el sitio en páginas de GitHub, Netlify u otro proveedor de alojamiento. También necesitará un editor de código avanzado, como VS Code.
Instalación de Nextra
Puedes usar un plantilla de documentos nextra para iniciar un sitio de documentación. Inicie un símbolo del sistema y navegue hasta el directorio en el que desea configurar su proyecto. Luego ejecute el siguiente comando para iniciar el sitio de documentación:
clonar https://github.com/shuding/nextra-docs-template
Este comando creará una aplicación dentro del directorio actual. A continuación, ejecute el siguiente comando para instalar las dependencias:
cd nextra-docs-plantilla
instalar npm
Una vez finalizada la instalación, inicie la aplicación. Hazlo ejecutando el siguiente comando en tu terminal:
npm ejecutar dev
Este comando inicia un servidor de desarrollo en localhost: 3000. Siga el enlace en su terminal para ver el sitio de documentación. La página de inicio debería verse así:
Si mira en el lado izquierdo de la página, encontrará las páginas nombradas Introducción y Otra página. Debajo de estos enlaces de página, encontrará una página llamada Satori, anidada dentro del Avanzado (una carpeta) directorio. Finalmente, en el área de navegación, encontrará enlaces a la Acerca de y Contacto paginas
Para comprender cómo funcionan estas páginas, primero deberá comprender cómo Next.js representa las páginas.
Comprender la estructura del directorio
Dado que Nextra usa el marco Next.js, representa cada archivo en el paginas/ carpeta como una página separada.
Dentro de paginas directorio, encontrará cuatro archivos de plantilla: sobre.mdx, avanzado.mdx, otro.mdx, y índice.mdx. Cada uno de estos archivos corresponde a una página del sitio web; Por ejemplo, índice.mdx corresponde a la página de inicio. la dirección URL servidor local: 3000/alrededor corresponde a sobre.mdx, etcétera.
Adentro paginas, también hay una carpeta llamada avanzado, que alberga un solo archivo llamado satori.mdx. La URL de este archivo será localhost: 3000/avanzado/satori.
Observe cómo cada uno de estos archivos termina con un .mdx extensión.
¿Qué es MDX?
Si usted tiene experiencia con reaccionar, debe saber acerca de JSX. Este es un lenguaje similar a HTML que puede usar para describir la interfaz de usuario de los componentes de React.
MDX carga, analiza y representa JSX en un documento Markdown. Gracias a MDX, puede escribir componentes React e importarlos a sus documentos Markdown cuando sea necesario. Los archivos MDX terminan con la extensión .mdx y pueden incluir Markdown y JSX.
MDX le permite combinar su conocimiento de Markdown con React para crear componentes reutilizables. Puede crear módulos CSS para dar estilo a los componentes. Esto le ayuda a organizar sus componentes para mejorar la legibilidad y la capacidad de mantenimiento.
Cómo editar páginas existentes en el sitio de documentación
Para editar una página existente, simplemente abra el archivo correspondiente y realice cambios en él. Los idiomas admitidos son Markdown y JSX.
Por ejemplo, abra el índice.mdx archivo y reemplace el contenido con esto:
# Bienvenido a Mi Documentación
Estoy feliz de verte aquí. Gracias
## Mis redes sociales
Sígueme en [Gorjeo](https://twitter.com/kingchuuks) y [LinkedIn](https://linkedin.com/in/kingchuks)
Este ejemplo usa Markdown para formatear el contenido. Contiene un encabezado de nivel uno, un encabezado de nivel dos y dos enlaces de redes sociales.
Guarde el archivo y visite la página de inicio de su sitio de documentación. La página ahora debería verse así:
En la parte inferior de la página, también puede encontrar la última fecha de actualización del documento.
Agregar una nueva página
Antes de agregar una nueva página, primero debe decidir si la página estará en el paginas/ directorio o dentro de una carpeta dentro de él. Utilice carpetas si desea categorizar sus páginas o desarrollar una jerarquía.
En este caso, cree una página independiente en el nivel superior. Abra un archivo llamado instalacion.mdx en su editor de código y pegue el siguiente código Markdown en él:
# Guía de instalación
Siga esta guía para instalar mi paquete en su proyecto## 1. Instalar Node.js
Para instalar Node.js, visite el
[Sitio de documentación de Node.js](https://nodejs.org/en/download)
Guarde el archivo y verifique el navegador. Encontrarás la etiqueta de Instalación en el menú lateral. Al hacer clic en el enlace, el contenido de instalacion.mdx renders en la página:
Puedes cambiar la etiqueta y realizar otras configuraciones en el archivo _meta.json dentro del directorio de páginas. Para obtener más información al respecto, consulte el Organizar archivos Sección de Documentación de Nextra.
Uso de componentes de reacción
Los archivos MDX pueden incluir JSX, que es el lenguaje que usa React. Puede crear un componente dentro de la carpeta de componentes e importarlo en cualquiera de los documentos de su sitio.
Puede ver un ejemplo de cómo puede incrustar componentes en Markdown en el otro.mdx archivo:
## Componente
importar {useState} desde 'reaccionar'
importar estilos desde '../components/counters.module.css'exportar const Contador = () => {
const [contar, establecerContar] = usarEstado (0);
devolver(
Hizo clic {contar} veces
)
}
<Encimera />
## Componentes externos
importar contadores desde '../components/counters'
<Contadores />
Este archivo Markdown contiene una definición para el componente Contador. Después de eso, importa el componente Contadores desde el componentes directorio.
Si va a usar el mismo componente en su sitio de documentación, es mejor crearlo como un componente independiente e importarlo cuando lo necesite.
Obtenga más información sobre las rebajas
Para crear contenido para su sitio de documentación, necesita saber cómo usar Markdown. La buena noticia es que la sintaxis de Markdown es bastante fácil de aprender. Cuando combina su conocimiento de Markdown con React, puede crear sitios de documentación realmente sólidos.
