网站导航

概述

提供网站导航有多种选项，包括：

• 使用顶部导航（导航栏），可选子菜单。

• 使用侧边导航，包含页面层级。

• 结合顶部和侧边导航（顶部导航链接到网站的不同部分，每个部分有自己的侧边导航）。

此外，您可以为顶部或侧边导航界面添加全文搜索功能。

顶部导航

要为网站添加顶部导航，请在 _quarto.yml 中的 website 配置中添加一个 navbar 条目。例如，以下 YAML：

website:
  navbar:
    background: primary
    search: true
    left:
      - text: "首页"
        href: index.qmd
      - talks.qmd
      - about.qmd 

结果将生成一个类似于以下的导航栏：

我们在上面使用 left 选项来指定导航栏左侧的项目。您还可以使用 right 选项来指定右侧的项目。

导航栏项目的文本将取自底层目标文档的标题。请注意，在上面的示例中，我们为 index.qmd 提供了自定义的 text: "首页" 值。

您还可以通过包含一个 menu（与 left 和 right 类似的列表项）来创建导航栏菜单。例如：

left:
  - text: "更多"
    menu:
      - talks.qmd
      - about.qmd 

以下是顶部导航的所有可用选项：

选项	描述
title	导航栏标题（如果未指定，则使用 site: title）。使用 title: false 来抑制导航栏上的标题显示。
logo	显示在标题左侧的标志图像。
logo-alt	标志图像的替代文本。
logo-href	从导航栏标志/标题指向的目标 href。默认情况下，标志和标题链接到网站的根页面（/index.html）。
background	背景颜色（“primary”、“secondary”、“success”、“danger”、“warning”、“info”、“light”、“dark” 或十六进制颜色）。
foreground	前景颜色（“primary”、“secondary”、“success”、“danger”、“warning”、“info”、“light”、“dark” 或十六进制颜色）。前景颜色将用于导航栏中的导航元素、文本和链接的颜色。
search	包含搜索框（true 或 false）。
tools	导航栏工具列表（例如，链接到 GitHub 或 Twitter 等）。详见 导航栏工具。
left / right	导航栏左侧和右侧的导航项列表。
pinned	始终显示导航栏（true 或 false）。默认为 false，并使用 headroom.js 在用户向上滚动页面时自动显示导航栏。
collapse	当显示变窄时，将导航栏项目折叠成汉堡菜单（默认为 true）。
collapse-below	响应式断点，用于在导航栏项目折叠成汉堡菜单时的位置（“sm”, “md”, “lg”, “xl” 或 “xxl”，默认为 “lg”）。
toggle-position	响应模式下折叠导航栏汉堡菜单的位置（“left” 或 “right”，默认为 “left”）。
tools-collapse	当显示变窄时，将工具折叠到导航栏菜单中。

以下是适用于单个导航项目的选项：

选项	描述
href	链接到项目内文件或外部 URL。
text	导航项目的显示文本（如果未提供，默认为文档的 title）。
icon	Bootstrap 5 图标 中的一个标准图标名称（例如 “github”, “twitter”, “share” 等）。
aria-label	导航项目的可访问标签。
rel	rel 属性的值。允许使用多个空格分隔的值。
target	target 属性的值。例如，_blank 在新标签页中打开。
menu	用于填充下拉菜单的导航项目列表。

有关使用 HTML 主题控制导航栏外观的更多信息，请参阅 HTML 主题 - 导航。

导航栏工具

人工智能与机器学习

概述

人工智能（AI）和机器学习（ML）是当今科技领域最热门的话题之一。AI是指计算机系统能够执行通常需要人类智能的任务，如视觉识别、语音识别和决策制定。ML是AI的一个子集，专注于开发能够从数据中学习的算法。

关键技术

深度学习

深度学习是ML的一个分支，使用多层神经网络来模拟人脑的工作方式。它在图像和语音识别等领域取得了显著的成功。

强化学习

强化学习是一种通过试错来学习的ML方法。它通常用于游戏和机器人控制等领域。

应用

医疗保健

AI和ML在医疗保健领域有广泛的应用，包括疾病诊断、药物发现和个性化治疗。

金融

在金融领域，AI和ML用于风险管理、欺诈检测和投资策略优化。

挑战

数据隐私

随着AI和ML的发展，数据隐私成为一个重要问题。如何在利用数据的同时保护个人隐私是一个亟待解决的挑战。

伦理问题

AI和ML的决策过程往往不透明，这引发了关于算法偏见和伦理责任的讨论。

未来展望

AI和ML的未来充满希望，但也伴随着挑战。随着技术的进步，我们有望看到更多创新应用的出现，但同时也需要解决随之而来的伦理和社会问题。

除了传统导航外，导航栏还可以显示一组工具（例如，社交操作、GitHub 查看或编辑操作等）。工具定义由一个图标名称和一个点击时跟随的 href 组成。对于图标，使用 1,300 多个 Bootstrap 图标中的任何一个图标名称。

例如：

website:
  navbar:
    tools:
      - icon: twitter
        href: https://twitter.com
      - icon: github
        menu:
          - text: Source Code
            href:  https://code.com
          - text: Report a Bug
            href:  https://bugs.com

为导航栏指定的工具将显示在导航栏的右侧。如果为网站指定了深色主题或阅读器模式，这些选项的控件将与任何指定的工具一起出现。

当导航栏在小屏幕上折叠成菜单时，工具将放置在菜单的底部。

侧边导航

如果你的网站包含不止几个文档，你可能更倾向于使用侧边导航，这样可以显示任意深度的文章层次结构。

如果你在桌面设备上阅读此页面，你将看到左侧默认的侧边导航显示（否则你将看到顶部的一个标题栏，点击或触摸它可以显示导航）。

要向网站添加侧边导航，请在 _quarto.yml 的 website 部分添加一个 sidebar 条目。例如：

website:
  sidebar:
    style: "docked"
    search: true
    contents:
      - text: "Introduction"
        href: introduction.qmd
      - section: "Basics"
        href: basics-summary.qmd
        contents:
          - index.qmd
          - basics-knitr.qmd
          - basics-jupyter.qmd
      - section: "Layout"
        contents:
          - layout.qmd
          - layout-knitr.qmd
          - layout-jupyter.qmd
      - section: advanced.qmd
        contents:
          - raw-code.qmd
          - custom-theme.qmd
      - acknowlegment.qmd

侧导航有两种风格可供选择：一种是“固定”风格，它在侧边栏中显示导航，并带有明显的背景颜色；另一种是“浮动”风格，它将导航放置在更靠近主体文本的位置。以下是“固定”和“浮动”风格的外观（分别）：

以下是侧导航的所有可用选项：

选项	描述
id	可选标识符（仅用于混合导航，如下所述）。
title	侧边栏标题（如果未指定，则使用项目标题）。
subtitle	可选副标题。
logo	可选的徽标图像。
logo-alt	徽标图像的替代文本。
logo-href	侧边栏徽标的目标链接。默认情况下，徽标和标题链接到网站的根页面（/index.html）。
search	包含搜索框（true或false）。请注意，如果顶部导航栏中已经有一个搜索框，侧边栏将不会显示。
tools	侧边栏工具列表（例如，链接到GitHub或Twitter等）。详细信息请参见下一节。
contents	要显示的导航项列表（通常顶级项会有一个子项列表）。
style	“固定”或“浮动”。
type	“dark” 或 “light”（提示确保文本颜色与背景颜色相反）。
background	背景颜色（“none”, “primary”, “secondary”, “success”, “danger”, “warning”, “info”, “light”, “dark”, 或 “white”）。默认为 “light”。
foreground	前景颜色（“primary”, “secondary”, “success”, “danger”, “warning”, “info”, “light”, “dark”, 或十六进制颜色）。前景颜色将用于侧边栏中的导航元素、文本和链接的颜色。
border	是否在侧边栏显示边框。“true” 或 “false”。
alignment	对齐方式（“left”, “right”, 或 “center”）。
collapse-level	是否默认折叠侧边栏导航。默认值为 2，显示顶层和下一层完全展开（但保留第三层及后续层级折叠）。
pinned	始终显示一个标题栏，在更窄的屏幕宽度下展开以显示侧边栏（true 或 false）。默认为 false，并使用 headroom.js 在用户向上滚动页面时自动显示导航栏。

一个没有 id 或 title 的 sidebar 项目将导致一个应用于所有页面的全局侧边栏。带有 id 或 title 的侧边栏将仅应用于侧边栏内容内的页面或指定侧边栏 id 的页面。

有关使用 HTML 主题控制侧导航外观的更多信息，请参阅 HTML 主题 - 导航。如果您需要控制侧边栏的宽度，请参阅 页面布局 - 网格定制。

自动生成

上面我们描述了如何使用导航项目显式填充侧边栏的 contents。您还可以从文件系统自动生成侧边栏导航。最直接的方法是指定 contents 选项如下：

sidebar:
  contents: auto

在根级别使用 contents: auto 将导致您的网站中的所有文档都包含在导航中（首页除外，可以通过标题链接导航到）。导航是根据以下规则构建的：

1. 导航项目标题将从文档的 title 字段中读取。

2. 子目录将创建部分，并根据目录名称自动命名（包括添加大写并替换破折号和下划线为空格）。如果不喜欢自动生成的名称，可以在目录中使用 index.qmd 提供明确的 title。

3. 顺序按字母顺序（按文件名），除非在文档元数据中提供了数值 order 字段。

自动导航自动包含子目录中的项目。如果不喜欢这样做，可以使用显式的 /* 来仅表示根目录中的文档：

sidebar:
  contents: /*

除了指定所有文档应包含在内，您还可以指定目录名或全局模式。例如，以下 contents 的值都是有效的（注意 reports 的第二种形式是非递归的）：

sidebar:
  contents: reports
  
sidebar:
  contents: reports/*
  
sidebar:
  contents: "*.ipynb"

请注意，在 YAML 中我们需要引用任何以 * 开头的字符串（如上面 *.ipynb 所示）。

您可以在侧边栏层次结构中的任何位置自动构建侧边栏 contents。例如，这里我们添加了一个从目录自动生成的部分：

sidebar:
  contents:
    - about.qmd
    - contributing.qmd
    - section: Reports
      contents: reports

您还可以通过包含带有 auto 属性的项目，在普通项目的中间包含自动生成的项目。这里我们在项目列表中间添加了一个 auto 条目：

sidebar:
  contents:
    - about.qmd
    - contributing.qmd
    - auto: "*-report.qmd"

请再次注意，我们引用了带有 * 的 auto 条目，以便正确解析。

侧边栏工具

除了传统的导航外，侧边栏还可以显示一组工具（例如，社交操作、GitHub查看或编辑操作等）。工具定义由一个图标名称和一个点击时跟随的href组成。对于icon，使用Bootstrap Icons中的任何1,300+个图标的名称。

例如：

website:
  sidebar:
    tools:
      - icon: twitter
        href: https://twitter.com
      - icon: github
        menu:
          - text: Source Code
            href:  https://code.com
          - text: Report a Bug
            href:  https://bugs.com

混合导航

如果你有一个包含几十甚至上百页的网站，你可能会希望同时使用顶部和侧边导航，其中顶部导航链接到各个部分，每个部分都有自己的侧边导航。

要做到这一点，提供一组sidebar条目，并通过匹配它们的title将每一组sidebar条目与一个navbar条目链接起来，并将从navbar链接的页面作为sidebar组中的第一个内容列出。例如，如果你在文档中使用Diátaxis框架，你可能会有单独的部分用于教程、操作指南、解释和参考文档，你的页面可能看起来像下面这样。

使用混合导航，如果你点击“教程”，你可能会进入类似下面的页面。

要实现这种布局，你的网站配置需要看起来像这样：

website:
  title: ProjectX
  navbar:
    background: primary
    search: true
    left:
      - text: "首页"
        href: index.qmd
      - text: "教程"
        href: tutorials.qmd
      - text: "操作指南"
        href: howto.qmd
      - text: "基础"
        href: fundamentals.qmd
      - text: "参考"
        href: reference.qmd

  sidebar:
    - title: "教程"
      style: "docked"
      background: light
      contents:
        - tutorials.qmd
        - tutorial-1.qmd
        - tutorial-2.qmd

    - title: "操作指南"
      contents:
        - howto.qmd
        # 导航项

    - title: "基础"
      contents:
        - fundamentals.qmd
        # 导航项

    - title: "参考"
      contents:
        - reference.qmd
        # 导航项
    

请注意，第一个侧边栏定义包含一些选项（例如style和background）。这些选项会自动被其他侧边栏继承。

另一种方法是使sidebar条目可以从与它们分组在一起的navbar条目的下拉菜单中访问。要做到这一点，提供一组sidebar条目并为它们中的每一个提供一个id，然后你就可以从navbar中引用它们。

Note

不在任何侧边栏中出现的页面将继承并显示第一个没有id或title的侧边栏 - 你可以通过在页面的前言中设置sidebar: false来阻止侧边栏在该页面上显示。

要实现这一点，你的网站配置需要看起来像这样：

website:
  title: ProjectX
  navbar:
    background: primary
    search: true
    left:
      - text: "主页"
        href: index.qmd
      - sidebar:tutorials
      - sidebar:howto
      - sidebar:fundamentals
      - sidebar:reference

  sidebar:
    - id: tutorials
      title: "教程"
      style: "固定"
      background: light
      collapse-level: 2
      contents: 
        # 导航项
        
    - id: howto
      title: "操作指南"
      contents:
        # 导航项
        
    - id: fundamentals
      title: "基础知识"
      contents: :
        # 导航项
        
    - id: reference
      title: "参考资料"
      contents: 
        # 导航项
    

面包屑导航

默认情况下，导航面包屑会显示在每个页面的页面标题上方，该页面在侧边栏导航中嵌套的深度超过一级。例如，给定以下 sidebar 定义：

website:
  sidebar:
    - contents:
      - section: "教程"
        contents:
          - text: "教程首页"
            href: tutorials.qmd

页面 tutorials.html 包含以下面包屑导航：

你可以通过 bread-crumbs 选项禁用整个网站的面包屑导航：

_quarto.yml

website:
  bread-crumbs: false

你也可以在单个页面上禁用面包屑导航：

document.qmd

---
title: 无面包屑导航的页面
bread-crumbs: false
---

页面导航

如果你有一个包含多个页面的小节或子小节的website，通常很方便为用户提供在阅读完当前页面后导航到下一页（或上一页）的功能。你可以通过以下方式启用此功能：

website:
  page-navigation: true

启用后，每当存在下一页或上一页（包括下一节或上一节）时，页面导航将显示在页面底部。此选项默认对书籍启用，但对网站不启用。

你还可以通过在YAML头部指定page-navigation来在页面级别启用或禁用页面导航，例如：

basics.qmd

---
page-navigation: false
---

或者，要控制目录中所有页面的页面导航，请在_metadata.yml中指定page-navigation：

_metadata.yml

page-navigation: false

分隔符

如果在侧边栏中包含页面分隔符（无论是在章节之间还是项目之间），页面导航控件将不会出现在分隔符上继续分页。例如，在以下侧边栏中：

website:
  sidebar:
    contents:
      - section: "第一部分"
        contents:
          - href: document1.qmd
          - href: document2.qmd
          - href: document3.qmd
      - text: "---"
      - section: "第二部分"
        contents:
          - href: document4.qmd
          - href: document5.qmd
          - href: document6.qmd

当用户到达 document3.qmd 的底部时，他们将看到返回 document2.qmd 的上一页导航，但不会看到继续到 document 4 的下一页导航。当你有内容部分不自然地按顺序流动时，这种行为很有用。使用分隔符在侧边栏中用水平线表示这一点，并打破分页。

返回顶部

你可以在网站的文档底部包含一个“返回顶部”链接，使用 back-to-top-navigation 选项。例如：

website:
  back-to-top-navigation: true

请注意，你可以通过指定 back-to-top-navigation: false 在逐页基础上禁用返回顶部导航。

页面页脚

使用 page-footer 选项为 website 中的所有页面提供一个通用的页脚。最简单的页脚仅提供居中显示的文本，并以较浅的字体显示：

website:
  page-footer: "版权所有 2021，诺拉·琼斯" 

你也可以分别针对页脚的 left、right 和 center 区域进行设置：

website:
  page-footer: 
    left: "版权所有 2021，诺拉·琼斯" 
    right: 
      - icon: github
        href: https://github.com/
      - icon: twitter 
        href: https://twitter.com/ 

请注意，对于页脚的 right 区域，我们包含了指向 GitHub 和 Twitter 的导航项，而不是文本。你可以在页脚的任何区域包含导航项。

你可以使用 background、foreground 和 border 选项进一步控制页脚的外观。默认情况下，页脚没有背景颜色，但有一个顶部边框。要消除边框，你可以这样做：

website:
  page-footer:
    border: false

要使用浅色背景（例如，与导航栏匹配），你可以这样做：

website:
  page-footer:
    background: light

除非另有指定，否则页脚中出现的元素所使用的颜色（foreground）将自动根据与页脚背景形成对比的颜色来确定。

隐藏导航

对于某些页面（尤其是那些具有完全自定义布局的页面），你可以完全隐藏导航（navbar、sidebar 或两者）。在这种情况下，将以下内容添加到页面前言中：

# 在此页面上隐藏侧边栏
sidebar: false

# 在此页面上隐藏导航栏
navbar: false

阅读器模式

如果你希望用户能够隐藏侧边导航和目录，并获得更专注的阅读体验，可以启用 reader-mode。启用后，如果在导航栏上存在，reader-mode 切换按钮将出现在导航栏上，或者出现在侧边栏上。按下后，切换按钮将“卷起”侧边栏和目录。

要启用 reader-mode，请在你的项目中使用以下内容：

website:
  reader-mode: true

网站搜索

你可以通过在 site-navbar 或 site-sidebar 配置中包含 search: true 来添加网站搜索。例如：

website:
  sidebar:
    style: "docked"
    search: true
    contents:
      - section: "基础"
        contents:
          - index.qmd
          - basics-jupyter.md
        # 等等

GitHub 链接

你可以为托管网站源代码的 GitHub 仓库添加各种链接（例如编辑页面、报告问题等）。为此，请添加 repo-url 以及一个或多个 repo-actions 中的操作。例如：

website:
  repo-url: https://github.com/quarto-dev/quarto-demo
  repo-actions: [edit, source, issue]

链接将显示在页面目录的正下方：

有两个额外的选项可以让你自定义仓库链接的行为：

选项	描述
repo-subdir	包含源文件的仓库子目录（默认为根目录）。
repo-branch	包含源文件的仓库分支（默认为 main）
issue-url	为’报告问题’操作提供显式 URL。
repo-link-target	用于仓库操作链接的 target 属性。例如，设置为 “_blank” 以在新标签或窗口中打开。
repo-link-rel	用于仓库操作链接的 rel 属性。

如果你想在特定页面上抑制 GitHub 链接，可以在文档 YAML 中将 repo-actions 设置为 false：

page.qmd

---
repo-actions: false
---

重定向

如果你重命名或移动了网站上的页面，你可能希望从旧的 URL 创建重定向，以使现有的链接不会失效。你可以通过在重命名的页面上添加 aliases 来实现这一点。

例如，假设你将 page.qmd 重命名为 renamed-page.qmd。你可以在 renamed-page.qmd 中添加以下 aliases 条目来创建重定向：

---
title: "Renamed Page"
aliases:
  - page.html
---

这在重新组织网站内容或将一个大文章拆分成多个小文章时也很有用。在这种情况下，你可能希望添加你已拆分到新页面的部分的 URL hash。例如：

---
title: "Learning More"
aliases:
  - overview.html#learning-more
---

Tip

根据你部署网站的位置，可能有更强大的工具可用于基于模式定义重定向。例如，Netlify 的 _redirects 文件或 .htaccess 文件。搜索你的网站主机的文档中的 “redirects”，看看是否有这些工具可用。

404 页面

当浏览器无法找到请求的网页时，它会显示一个 404 错误，表示文件无法找到。浏览器默认的 404 页面可能相当简陋，因此你可能希望创建一个带有更友好消息的自定义页面，并可能提供一些关于用户如何找到他们正在寻找的内容的提示。

大多数网络服务平台（例如，Netlify、GitHub Pages 等）会使用你网站根目录下的名为 404.html 的文件作为自定义错误页面（如果你提供了的话）。你可以在 Quarto 网站中通过在项目的根目录下创建一个名为 404.qmd 的 markdown 文件来包含一个自定义的 404 页面。例如：

---
title: Page Not Found
---

你请求的页面无法找到（可能它被移动或重命名了）。

你可能想尝试搜索以找到页面新的位置。

注意，你可以在 404.qmd 文件中使用 HTML 与 markdown 结合，以获得你想要的外观和布局。

你的 404 页面将出现在你网站的 chrome 中（例如，字体、CSS、布局、导航等）。这样，当用户遇到 404 错误时，他们不会感到已经不可逆地“离开”了你的网站。如果你不希望这种行为，那么请提供一个 404.html 而不是 404.qmd。

以下是一些流行网站如何处理自定义 404 页面的示例：https://blog.fluidui.com/top-404-error-page-examples/。

非根站点路径

如果你的网站是从域名的根路径提供的（例如，https://example.com/），那么只需提供如上所述的 404.qmd 文件即可创建自定义的 404 页面。

然而，如果你的网站不是从域名的根路径提供的，那么你需要提供额外的配置，以确保 404 页面中的资源（例如，你网站的 CSS）能够正确解析。

例如，如果你的网站是从 https://example.com/mysite/ 提供的，那么你需要在你的项目 website 配置中添加以下内容到 _quarto.yml：

website:
  title: "My Site"
  site-path: "/mysite/"

注意，如果你已经提供了 site-url（这是生成站点地图和 社交元数据 预览图像所必需的），那么只需在 site-url 中包含路径即可：

website:
  title: "My Site"
  site-url: "https://example.com/mysite/"