jigsaw docs template

Plantilla inicial de documentos de Jigsaw

Esta es una plantilla inicial para crear un sitio de documentación hermoso y personalizable para su proyecto con el mínimo esfuerzo. Sólo tendrás que cambiar algunas configuraciones y estarás listo para comenzar.

Vea una vista previa de la plantilla de documentos.

Instalación

Después de instalar Jigsaw, ejecute el siguiente comando desde el directorio de su proyecto:

./vendor/bin/jigsaw init docs

Esta plantilla inicial incluye ejemplos de tipos de páginas comunes y viene preconfigurada con:

• Una barra de navegación totalmente responsiva
• Un menú de navegación en la barra lateral
• Tailwind CSS, un framework CSS de utilidad que te permite personalizar tu diseño sin tocar una línea de CSS
• Purguecss para eliminar selectores no utilizados de su CSS, lo que da como resultado archivos CSS más pequeños
• Resaltado de sintaxis usando resaltado.js
• Un script que genera automáticamente un archivo sitemap.xml
• Una barra de búsqueda impulsada por Algolia DocSearch e instrucciones sobre cómo comenzar con su servicio de indexación gratuito.
• Una página 404 personalizada

---

---

Configurando su nuevo sitio

Como ocurre con todos los sitios de Jigsaw, los ajustes de configuración se pueden encontrar en config.php ; puede actualizar las variables en ese archivo con configuraciones específicas para su proyecto. También puede agregar nuevas variables de configuración allí para usarlas en su sitio; Eche un vistazo a la documentación de Jigsaw para obtener más información.

 // config.php
return [
    ' baseUrl ' => ' https://my-awesome-jigsaw-site.com/ ' ,
    ' production ' => false ,
    ' siteName ' => ' My Site ' ,
    ' siteDescription ' => ' Give your documentation a boost with Jigsaw. ' ,
    ' docsearchApiKey ' => '' ,
    ' docsearchIndexName ' => '' ,
    ' navigation ' => require_once ( ' navigation.php ' ),
];

Consejo: Este archivo de configuración también es donde definirá las "colecciones" (por ejemplo, una colección de los contribuyentes a su sitio o una colección de publicaciones de blog). Consulte la documentación oficial de Jigsaw para obtener más información.

---

Agregar contenido

Puede escribir su contenido utilizando una variedad de tipos de archivos. De forma predeterminada, esta plantilla inicial espera que su contenido esté ubicado en la carpeta source/docs . Si cambia esto, asegúrese de actualizar las referencias de URL en navigation.php .

La primera sección de cada página de contenido contiene un encabezado YAML que especifica cómo se debe representar. El atributo title se utiliza para generar dinámicamente title HTML y etiquetas OpenGraph para cada página. El atributo extends define con qué diseño principal de Blade se representará este archivo de contenido (por ejemplo, _layouts.documentation se representará con source/_layouts/documentation.blade.php ), y el atributo section define la "sección" de Blade que espera que se coloque este contenido. en ello.

---
title : Navigation
description : Building a navigation menu for your site
extends : _layouts.documentation
section : content
---

Lea más sobre los diseños de Jigsaw.

---

Agregar activos

Cualquier activo que deba compilarse (como archivos JavaScript, Less o Sass) se puede agregar al directorio source/_assets/ , y Laravel Mix los procesará cuando se ejecute npm run dev o npm run prod . Los activos procesados ​​se almacenarán en /source/assets/build/ (tenga en cuenta que no hay guiones bajos en este segundo directorio de assets ).

Luego, cuando Jigsaw cree su sitio, todo el directorio /source/assets/ que contiene sus archivos creados (y cualquier otro directorio que contenga recursos estáticos, como imágenes o fuentes, que elija almacenar allí) se copiará a las carpetas de compilación de destino. ( build_local , en su máquina local).

Los archivos que no requieren procesamiento (como imágenes y fuentes) se pueden agregar directamente a /source/assets/ .

Lea más sobre cómo compilar recursos en Jigsaw usando Laravel Mix.

---

Construyendo su sitio

Ahora que ha editado sus variables de configuración y sabe cómo personalizar sus estilos y contenido, creemos el sitio.

 # build static files with Jigsaw
./vendor/bin/jigsaw build

# compile assets with Laravel Mix
# options: dev, prod
npm run dev