Crear documentación para la web

Para crear nueva documentación en el apartado "Docs" de la web, debemos irnos al directorio docs de la raíz del proyecto. Una vez allí, tenemos dos formas de crear documentación:

Crear una categoría de archivos

Cuando queremos tener un conjunto de archivos que traten sobre un mismo tema, lo mejor es crear una carpeta con el nombre de la categoría sobre la que queremos desarrollar y dentro de ella los archivos que traten sobre ese tema. Para ello, debemos seguir los siguientes pasos:

1. Crear la carpeta de la categoría: Para ello, debemos crear una carpeta con el nombre de la categoría en el directorio docs. El nombre puede ser cualquier cosa, pero es recomendable que sea descriptivo y sobre el tema a tratar. Por ejemplo, una carpeta sobre teoría cuántica podría llamarse teoria-cuantica.
2. Crear archivo de categoría: Para definir que el directorio será una categoría, debemos crear un archivo llamado _category_.json dentro de la carpeta. Este archivo debe tener la siguiente estructura:

{
  "label": "Teoria cuantica",
  "position": 99,
  "link": {
    "type": "generated-index",
    "description": "Explicando la teoria cuantica desde cero"
  }
}

Donde:

• label: Es el nombre que se mostrará en la web.
• position: Es la posición que ocupará en la lista de categorías. A menor número, más arriba estará en la lista.
• link: Es un objeto que define el enlace que se mostrará en la web. En este caso, se está definiendo un enlace a un archivo generado automáticamente.
  • type: Es el tipo de enlace. En este caso, se está definiendo un enlace a un archivo generado automáticamente. Se recomienda no cambiar este valor a menos que sepas lo que estás haciendo.
  • description: Es la descripción que se mostrará en la web.

3. Crear archivos de documentación: Dentro de la carpeta, podemos crear los archivos que queramos. Estos archivos deben tener extensión .md, que pertenece al lenguaje Markdown.

4. Añadir carpeta de imágenes: Si queremos añadir imágenes a la documentación, debemos crear una carpeta llamada img dentro de la carpeta de la categoría y añadir las imágenes que queramos. Luego se podrán utilizar como siempre con Markdown o HTML en los archivos.

Crear un archivo suelto

Si queremos crear un archivo suelto, simplemente debemos crear un archivo con extensión .md en el directorio docs o dentro de la carpeta deseada de este directorio, como, por ejemplo, teoria-cuantica. Este archivo se mostrará directamente en el sidebar de la documentación general como link directo. Para el archivo, hay que recordar que hay que comenzarlo con la siguiente estructura:

---
title: Titulo del archivo
description: Descripción del archivo
hide_table_of_contents: false
---

Donde:

• title: Es el título que se mostrará en la web.
• description: Es la descripción que se mostrará en la web.
• hide_table_of_contents: Es un booleano que define si se mostrará la tabla de contenidos en la web. Si se pone a true, no se mostrará. Si se pone a false, se mostrará.