README

This is a starter template for creating a beautiful, customizable documentation site for your project with minimal effort. You’ll only have to change a few settings and you’re ready to go.

View a preview of the docs template.

Installation

After installing Jigsaw, run the following command from your project directory:

./vendor/bin/jigsaw init docs

This starter template includes samples of common page types, and comes pre-configured with:

• A fully responsive navigation bar
• A sidebar navigation menu
• Tailwind CSS, a utility CSS framework that allows you to customize your design without touching a line of CSS
• Syntax highlighting using Prism.js
• A script that automatically generates a sitemap.xml file
• A search bar powered by Algolia DocSearch, and instructions on how to get started with their free indexing service
• A custom 404 page

Configuring your new site

As with all Jigsaw sites, configuration settings can be found in config.php; you can update the variables in that file with settings specific to your project. You can also add new configuration variables there to use across your site; take a look at the Jigsaw documentation to learn more.

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

Tip: This configuration file is also where you’ll define any "collections" (for example, a collection of the contributors to your site, or a collection of blog posts). Check out the official Jigsaw documentation to learn more.

Adding Content

You can write your content using a variety of file types. By default, this starter template expects your content to be located in the source/docs folder. If you change this, be sure to update the URL references in navigation.php.

The first section of each content page contains a YAML header that specifies how it should be rendered. The title attribute is used to dynamically generate HTML title and OpenGraph tags for each page. The extends attribute defines which parent Blade layout this content file will render with (e.g. _layouts.documentation will render with source/_layouts/documentation.blade.php), and the section attribute defines the Blade "section" that expects this content to be placed into it.

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

Read more about Jigsaw layouts.

Adding Assets

Any assets that need to be compiled, such as JavaScript or CSS using Tailwind, can be added to the source/_assets/ directory. Vite will process them when running npm run dev or npm run build, and the processed assets will be stored in /build_local or /build_production, respectively.

Files that don't need processing (like images and fonts) can be placed in /source/assets/ and will be included in the build as-is.

Read more about compiling assets in Jigsaw using Vite.

Building Your Site

Now that you’ve edited your configuration variables and know how to customize your styles and content, let’s build the site.

# run development server
npm run dev

# build static files with Vite
npm run build