README

这是一个创建美观、可定制的项目文档网站的起始模板，只需更改少量设置即可快速使用。

查看文档模板的预览。

安装

在安装 Jigsaw 之后，从您的项目目录运行以下命令

./vendor/bin/jigsaw init docs

这个起始模板包括常见页面类型的示例，并预先配置了以下功能

• 一个完全响应式的导航栏
• 侧边栏导航菜单
• Tailwind CSS，这是一个功能型 CSS 框架，允许您在不触碰一行 CSS 的情况下自定义设计
• Purgecss 以从您的 CSS 中移除未使用的选择器，从而生成更小的 CSS 文件
• 使用 highlight.js 进行语法高亮
• 一个自动生成 sitemap.xml 文件的脚本
• 由 Algolia DocSearch 提供的搜索栏，以及如何开始使用他们的免费索引服务的说明
• 自定义 404 页面

配置您的网站

与所有 Jigsaw 网站一样，配置设置可以在 config.php 中找到；您可以在该文件中更新特定于项目的变量。您还可以添加新的配置变量以在网站上使用；请参阅 Jigsaw 文档 了解更多信息。

// 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'),
];

提示：此配置文件也是您定义任何 "集合"（例如，您的网站的贡献者集合，或博客文章集合）的地方。请参阅官方 Jigsaw 文档 了解更多信息。

添加内容

您可以使用多种文件类型（例如 其他文件类型）编写内容。默认情况下，此起始模板期望内容位于 source/docs 文件夹中。如果更改此设置，请确保更新 navigation.php 中的 URL 引用。

每个内容页面的第一部分包含一个 YAML 标头，该标头指定了其渲染方式。使用 title 属性动态生成每个页面的 HTML title 和 OpenGraph 标签。使用 extends 属性定义将使用哪个父 Blade 布局渲染此内容文件（例如，_layouts.documentation 将与 source/_layouts/documentation.blade.php 一起渲染），使用 section 属性定义期望将此内容放置其中的 Blade "section"。

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

了解更多关于 Jigsaw 布局的信息。

添加资产

需要编译的任何资产（例如 JavaScript、Less 或 Sass 文件）可以添加到 source/_assets/ 目录中，并在运行 npm run dev 或 npm run prod 时由 Laravel Mix 处理。处理后的资产将存储在 /source/assets/build/ 中（注意第二个 assets 目录中没有下划线）。

然后，当Jigsaw构建您的网站时，包含您的构建文件（以及您选择存储在该处的任何其他静态资源目录，例如图片或字体）的整个/source/assets/目录将被复制到目标构建文件夹（在您的本地机器上的build_local）。

不需要处理（例如图片和字体）的文件可以直接添加到/source/assets/。

有关使用Laravel Mix在Jigsaw中编译资源的相关信息，请参阅更多信息。

构建您的网站

现在您已经编辑了配置变量，并了解了如何自定义样式和内容，让我们来构建网站。

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

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