Cómo escribir una buena documentación con Docsify

Cómo escribir buena documentación con Docsify

La documentación es fundamental para un producto exitoso. Sin documentación, es más difícil para las personas utilizar tu producto, y también es igual de importante si estás administrando un proyecto de código abierto.

Crear un sitio de documentación puede ser desafiante, especialmente si no estás familiarizado con el desarrollo front-end.

He sido desarrollador front-end durante los últimos 8 años. Durante ese tiempo, he utilizado muchos frameworks para construir documentación, como Next.js, nextra, content layer, Ghost CMS, lume (deno), docusaurus y Mark doc.

Pero para utilizar muchos de ellos, necesitas tener conocimientos esenciales sobre JavaScript, Next.js y React. Puedes encontrarte con algunos desafíos, como:

1. Falta de conocimientos de JavaScript, React u otras herramientas necesarias
2. Versionado de documentación
3. Configuración
4. Implementación

En esta guía, te presentaré una herramienta poderosa que puede ayudarte a escribir documentación sin necesidad de tener tanto conocimiento técnico.

¿Qué es Docsify?

Para ayudarte a resolver este problema, recomendaría una herramienta llamada docsify. Docsify es un generador de documentación simple y liviano. Puedes comenzar a utilizarlo sin tener ningún conocimiento de JavaScript o React.

Docsify viene sin ninguna configuración, no utiliza archivos HTML generados estáticamente, admite múltiples temas, posee una API de complementos incorporada y admite búsqueda de texto completo con un complemento. También se puede implementar en una amplia gama de plataformas como GitHub pages, GitLab Pages, Firebase Netlify, Vercel y otras más.

He creado un proyecto de demostración para mostrarte cómo utilizarlo: el código fuente está disponible en GitHub. También puedes ver el sitio de demostración en vivo.

Cómo configurar y utilizar Docsify

Puedes crear un nuevo proyecto con docsify-cli. Para usar docsify-cli, debes instalar Node y NPM si aún no los tienes instalados.

npm install -g docsify-cli# o yarn add -g docsify-cli# o pnpm add -g docsify-cli

La salida de comando se verá así:

❯ pnpm add -g docsify-cliPackages: +198+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++Progress: resolved 199, reused 114, downloaded 84, added 198, done.pnpm/[email protected]/node_modules/docsify: Running postinstall script, done in 196ms/home/rajdeepsingh/.local/share/pnpm/global/5:+ docsify-cli 4.4.4+ pnpm 8.7.0Done in 13.9s

Crea tu nuevo proyecto con la opción init de docsify-cli.

➜ docsify init docs¡La inicialización fue exitosa! Por favor, ejecuta docsify serve ./docs

También puedes especificar el --theme y --plugins.

➜ docsify init docs --theme buble --plugins

Puedes leer más información sobre docsify-cli en la página de documentación.

A continuación, inicia tu servidor de desarrollo local utilizando docsify-cli. Para ello, ejecuta el siguiente comando:

docsify serve docs# odocsify serve .

Tu servidor local se ejecuta en el puerto 3000 localmente.

Tu sitio web debería verse así cuando lo abras en el navegador:

Estructura de carpetas de Docsify

Docsify tiene una estructura de carpetas sencilla. Por defecto, cuando creas un nuevo proyecto con docsify-cli, hay tres archivos principales:

├── index.html // Este es un archivo de entrada HTML.├── .nojekyll  // Esto es útil cuando despliegas tu proyecto en GitHub pages.└── README.md  // Esta es la página de inicio o la ruta /

Cómo personalizar Docsify

Docsify viene con muchas opciones de personalización, y no necesitas ningún conocimiento adicional para configurarlo, es bastante sencillo, como copiar y pegar código.

En esta guía, exploraremos algunas de las opciones de personalización más comunes. Para una configuración avanzada, puedes consultar la documentación de Docsify.

1. Configuración básica
2. Pantalla de carga
3. Barra lateral
4. Encabezado
5. Página de presentación
6. Plugins
7. Temas
8. Despliegue

Configuración básica

En la configuración básica, puedes cambiar o agregar un logo, un nombre, agregar el enlace a tu repositorio de GitHub, un color de tema, y mucho más.

Aquí está el código para hacer eso, puedes completar tus propios detalles.

 <!-- index.html --> <script>      window.$docsify = {        logo: '/_media/icon.svg',  <!-- agregar logo -->        name: "Document",  <!-- Nombre del sitio web que aparece en la barra lateral. -->        nameLink: '/',  <!-- URL para el nombre -->        repo: "officialrajdeepsingh/docsifyjs",<!--repositorio de GitHub-->        maxLevel: 2,  <!-- Nivel máximo de contenido del índice. -->        themeColor: '#3F51B5', <!-- Personalizar el color del tema -->      };</script>

Pantalla de carga

Habilitar una pantalla o diálogo de carga suele ser muy complicado, especialmente si provienes del ecosistema de JavaScript y React.js.

En Docsify, puedes habilitar una pantalla de carga sin necesidad de realizar ninguna configuración. Solo tienes que escribir un texto junto con un elemento HTML dentro de tu ID de aplicación, que se mostrará como una pantalla de carga. Se ve así:

<!-- index.html --><div id="app">Por favor, espera...</div><!-- or --><div id="app"><h1> Por favor, espera... </h1></div>

Barra lateral

Por defecto, la barra lateral muestra el índice de contenidos. Pero puedes personalizarla muy fácilmente. Primero, tendrás que habilitar la barra lateral.

<!-- index.html --><script>   window.$docsify = {               loadSidebar: true, <!-- Habilitar barra lateral -->     };</script>

Luego, crea un nuevo archivo _sidebar.md en el nivel raíz y pega el siguiente código:

- [Inicio](README.md)- [Artículo de borrador](draft-article.md)- [Guía](guide.md)- [Primero](page-first.md)- [Segundo](page-second.md)- [Tercero](page-third.md)- [Cuatro](page-four.md)

Ahora tu barra lateral debería lucir así:

Cabecera

Por defecto, no podrás ver la barra de navegación en tu sitio de Docsify:

Pero no te preocupes, puedes cambiar eso. Para mostrar la barra de navegación, primero debes activarla así:

<!-- index.html -->    <script>      window.$docsify = {                       loadNavbar: true,     <!-- activar barra de navegación -->             };    </script>  </body></html>

Luego, crea un nuevo archivo _navbar.md en el nivel raíz y pega el siguiente código:

* Empezando  * [Inicio rápido](quickstart.md)  * [Escribiendo más páginas](more-pages.md)  * [Barra de navegación personalizada](custom-navbar.md)  * [Página de portada](cover.md)* Configuración  * [Configuración](configuration.md)  * [Temas](themes.md)  * [Uso de complementos](plugins.md)  * [Configuración de Markdown](markdown.md)  * [Resaltado de lenguaje](language-highlight.md)

Ahora tu barra de navegación debería lucir así:

Página de Portada

Primero, activa la página de portada en docsify con el siguiente código:

<!-- index.html --><script>      window.$docsify = {               coverpage: true,     <!-- activar página de portada -->              };</script>

El siguiente paso es crear un nuevo archivo _coverpage.md.

# Aprende Docsify ### Aprende docsify desde principiante.[Comenzar aprendizaje]()[Github](#/README)

Tu página de portada del sitio web debería lucir así:

La página de portada y tu interfaz dependen del tema, por lo que pueden ser diferentes entre sí.

Complementos

Los complementos ayudan a proporcionar funcionalidad adicional y características a Dicsify y también mejoran la experiencia del usuario.

Puedes crear y utilizar complementos según tus propios requisitos. Docsify tiene muchos complementos disponibles que son de código abierto y creados por varios colaboradores.

Puedes utilizar cualquier complemento simplemente copiando y pegando el código. Incluso puedes crear tus propios complementos con docsify.

Cómo utilizar complementos de terceros

En este ejemplo, habilitaremos la funcionalidad de la barra de búsqueda con la ayuda del complemento de docsify.

Para habilitar la barra de búsqueda, copia y pega el siguiente script dentro de tu archivo index.html:

<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>

Ahora la barra de búsqueda aparecerá y funcionará en tu sitio. Con el complemento de búsqueda, también puedes configurar varias funcionalidades; obtén más información al respecto en la página de instalación y configuración del complemento de búsqueda.

Cómo crear tu propio plugin con docsify

Para crear tu propio plugin en docsify, necesitarás utilizar un gancho integrado en el plugin.

Docsify tiene seis ganchos integrados: init, mounted, beforeEach, afterEach, doneEach y ready.

1. init: se invoca una vez cuando el script de docsify se inicializa.
2. mounted: se invoca una vez cuando la instancia de docsify se ha montado en el DOM.
3. beforeEach: se invoca en cada carga de página antes de que el nuevo markdown se convierta en HTML.
4. afterEach: se llama en cada carga de página después de que el markdown se ha convertido en HTML.
5. doneEach: se invoca en cada carga de página después de que se ha añadido nuevo HTML al DOM.
6. ready: se invoca una vez después de renderizar la página inicial.

Con la ayuda de estos ganchos, puedes crear un plugin. Para obtener más información sobre la creación de tus propios plugins, consulta la página de documentos de plugins personalizados.

En este ejemplo, crearemos un botón de edición utilizando el gancho del plugin beforeEach. Mostrará el botón EDITAR DOCUMENTO en cada página.

<!-- index.html -->    <script>      window.$docsify = {                plugins: [                <!-- escribe tu propio plugin personalizado -->        function editButton(hook, vm) {          // llama al gancho          hook.beforeEach(function (html) {                       var url = "https://github.com/officialrajdeepsingh/docsifyjs/edit/master/" + vm.route.file;                          // corrección básica de ruta             let tempFile = url.replace("docsifyjs/README.md", "README.md",)              ? url.replace("docsifyjs/README.md", "README.md")              : url;            // Añade el botón Editar            var editHtml = "[📝 EDITAR DOCUMENTO](" + url + ")\n";            // Añade el botón de edición al principio del archivo            return editHtml + html + "\n----\n" + "Última modificación " + editHtml;          });        },        ],                      };    </script>

Temas

Docsify tiene tanto temas oficiales como temas hechos por la comunidad. Puedes utilizar cualquiera de ellos, y lo bueno es que no necesitas escribir ningún código adicional cuando cambias de tema.

<!-- tema Vue --><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" /><!-- tema Bubble --><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css" /><!-- tema oscuro --><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css" /><!-- tema Pure --><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css" />

Puedes elegir comprimir o no comprimir los archivos CSS de los temas. El archivo CSS comprimido es una versión minificada del tema y es un archivo CSS ligero para producción. Por otro lado, un archivo CSS de tema no comprimido es útil para el desarrollo.

Simplemente copia el archivo CSS del tema (Vue, Bubble, Oscuro y Pure) y pégalo dentro del elemento head. Y con eso, tu tema cambia.

En cuanto a los temas no oficiales, creo que el tema docsify-themeable es la mejor opción para ti.

Implementación

Docsify tiene varias opciones para la implementación. Puedes implementar tu sitio de Docsify en GitHub Pages, GitLab Pages, Firebase Hosting, VPS (Nginx), Netlify, Vercel, AWS Amplify y Docker.

En algunas plataformas como GitHub Pages, puedes implementar tu sitio de Docsify directamente desde el repositorio de GitHub sin escribir ninguna configuración.

Aquí está el proceso para hacerlo:

Ve a Configuración > Páginas > Fuente > y luego selecciona “Implantar desde una rama” > Rama > Selecciona tu rama con la carpeta y haz clic en el botón de guardar.

Esto tomará algún tiempo, dependiendo del tamaño de tu sitio web. Después de que la implementación termine, deberías ver tu URL de producción.

Conclusión

Docsify es una herramienta poderosa para generar sitios de documentación. En Docsify, puedes centrarte en escribir documentación y no en el diseño de la interfaz de usuario.

Docsify es una buena opción para los desarrolladores que no están muy familiarizados con JavaScript. Si te centras más en lenguajes de bajo nivel como C++ o Rust, Docsify puede ayudarte a comenzar a escribir tu documentación con un solo comando.

Recientemente usé Docsify para mi repositorio awesome-nextjs. Puedes implementarlo fácilmente en la página de GitHub sin ninguna configuración.

Solo ten en cuenta que hay dos desventajas de Docsify:

1. Docsify no genera etiquetas meta dinámicas de SEO para una página. Solo genera un título y una descripción.
2. El tema de Docsify no proporciona una sensación de interfaz de usuario moderna.

Pero ¡sigue siendo muy útil! Disfruta creando tu documentación 🙂

• Documentation