GitHub Wiki中的ToC或侧边栏

Question

如何在GitHub Wiki中创建目录或侧边栏菜单？

我看到一些提到它和gollum后端似乎支持它，但如何在当前的GitHub项目中实现呢？

最好是基于页面标题自动生成。

这些链接都提到了它，但没有展示如何实现：

• https://gist.github.com/379469 - 一些JavaScript小技巧

• https://github.com/blog/774-git-powered-wikis-improved - GitHub提到：

  "GitHub Wikis拥有一个鲜为人知的页脚和侧边栏能力，这是我们一些基于git的Wiki作者熟悉的。新的Wiki编辑器为您提供了有限的网页编辑功能，以编辑您站点上的页脚和侧边栏。"

- wolle

---

我开发了GitHub Wikifier：一个预提交的Git Hook，它会生成你所需的所有目录。只需编写内容即可让它接管。可能值得一试。https://github.com/kuroir/GitHub-Wikifier - MarioRicalde

关于Isaacs：https://github.com/isaacs/github/issues/504 - Ciro Santilli OurBigBook.com

@MarioRicalde 的代码已经迁移到 https://github.com/hybridgroup/GitHub-Wikifier。 - Jonny

Answer 1

虽然你的解决方案可行，但使用GitHub的Web界面有一种更简单的方法。您可以创建一个名为_Sidebar和/或_Footer的页面。

请参阅详细说明 Github Wiki带有多级菜单生成器的侧边栏菜单.

编辑 原文章已经消失了，我找不到它在缓存中，所以我更新了链接。

- nicerobot

---

@CodeSherpa，它们可以在 https://github.com/[user]/[repo]/wiki/_Sidebar/_edit 和 https://github.com/[user]/[repo]/wiki/_Footer/_edit 上找到。 - nicerobot

这篇文章很棒，但是提供了关于如何获取维基URL的错误（或过时）信息。如果你和我一样迷失了方向，你需要使用URL https://github.com/<username>/<projectname>.wiki.git 或 SSH [e-mail]:<username>/<projectname>.wiki.git。 - NightOwl888

这些详细说明相当差劲。什么是[[link]]？在那里放置一个URL会导致整个URL显示出来。 - Pithikos

@Pithikos 这是 Github Markdown 语言。这些说明不是为了教你如何使用 Markdown，而是为了解释侧栏。 - nicerobot

@nicerobot，解释某个东西最好的方法是使用具体的例子。 - Pithikos

Answer 2

当您在项目的维基页面时，会有一个名为“添加自定义侧边栏”的链接。请点击该链接。

现在您有一个页面，可以像编辑任何其他Markdown页面一样进行编辑。但是，要制作目录，您必须手动完成。目前还没有自动化的方法（截至2014年8月）。例如：

# My menu
* [Home][home]
* [Technical documentation][techdocs]
* [User manual][usermanual]

[home]: https://github.com/myproject/wiki/Home
[techdocs]: https://github.com/myproject/wiki/Technical-documentation
[usermanual]: https://github.com/myproject/wiki/User-manual

- Pithikos

---

这个已经不再可用了，至少在非企业版中是这样的。 - playmobilmeister

这个已经不再可用了，至少在非企业版中是这样的。 - playmobilmeister

Answer 3

好的，让我看看是否理解正确：

1. 克隆你的GitHub维基页面。（在维基页面中有Git部分。您可以检出类似于维基代码的内容）
2. 创建_Sidebar.md
3. 在普通维基页面中，使用[[link]]来设置侧边栏
4. 提交并将更改推回GitHub

这个过程很麻烦。我很惊讶这个“gollum”维基页面能够被接受。

另外：_Sidebar.md因此是所有页面的全局设置。我需要将我的维基页面组织成文件夹，以便为不同的页面定义不同的侧边栏。

- wolle

---

根据文档，您可以为不同的文件夹添加不同的侧边栏：“侧边栏会影响其目录下的所有页面以及任何没有自己的侧边栏文件的子目录。”参见：https://github.com/github/gollum - Subfuzion

根据文档，您可以为不同的文件夹添加不同的侧边栏。但有人能够可靠地让它工作吗？我发现这样做会放弃通过UI编辑侧边栏的能力。您最终要编辑的特定侧边栏似乎不稳定和不可靠。我可以没有UI进行编辑(git/直接编辑)。然而，我发现它不能可靠地工作。有时会使用/显示子文件夹的侧边栏，但有时候根侧边栏“渗透”。似乎无法正常工作。 - ScottWelker

Answer 4

注意：原问题是关于创建侧边栏（容易，在答案中解决）或者实际目录（未得到解答）。

我可以说的一件事情是，Gollum 2.1 wiki 语法允许使用 [[_TOC_]] 标签，但是 GitHub wiki 目前无法识别它。

- mark

---

你有什么进展吗？这太令人沮丧了，因为在 Trac 上所有这些事情都很容易完成。请注意，我已经尽力使翻译准确并符合中文语境和习惯用语。 - jooks

我认为对于如何自动创建基于页面标题的目录的原始问题，更好的答案是在GitHub Wiki中目前无法实现。 - avernet

这是目前一个未解决问题（懒得去查编号），已有数百人发表了评论。GitHub 还没有回复任何消息 :( - abalter

截至2017年1月19日，主要的GitHub问题参考如下：

1. Markdown - 目录
2. 在渲染的Markdown文件（如README.md）中插入自动生成的目录TOC

- ckib16

GitHub将为AsciiDoc维基页面创建目录。https://github.com/dogweather/github-wiki-toc-demo/wiki - Dogweather

Answer 5

我认为这在 GollumREADME 中有所描述（请参见标题和侧边栏部分）。

基本上，您需要在包含页面内容的目录中创建_footer.ext 和 _sidebar.ext。

- seandavi

Answer 6

我已经实现了npm模块github-wiki-sidebar，帮助github用户轻松创建和维护边栏菜单。

源和结果: https://raw.githubusercontent.com/wiki/adriantanasa/github-wiki-sidebar/images/github-wiki-sidebar-generator.png 源页面(在Wiki管理中显示):

Home
Installation
Roadmap
Usage
Usage: Command line modifiers
Usage: Init Mode

结果（自定义顺序）：

• 主页
• 安装
• 用法
  • 初始化模式
  • 命令行修改器
• 路线图

先决条件：

• clone your github wiki repository locally (displayed on the bottom-right of the Wiki UI)

• install the github-wiki-sidebar

  git clone <https://github.com/<username>/<my-project-name>.wiki.git
  npm install -g github-wiki-sidebar
  

创建/更新您的维基菜单：

• create new pages / rename pages on your github.com wiki admin

• execute locally the github-wiki-sidebar script in your wiki repository folder

  cd /path/to/<my-project-name>.wiki
  # this fetches latest changes, generates sidebar file (_Sidebar.md) and pushes changes to github
  github-wiki-sidebar --git-push
  

该模块允许自定义Markdown输出，包括项目排序、类别分隔符、菜单模板、链接格式等。

- adtanasa

Answer 7

如果您想使用可展开的菜单（也称为下拉菜单），请使用_Sidebar.asciidoc，并使用AsciiDoc标记语法[%collapsible]。

您仍然可以在链接中引用普通的Markdown :) 请记住，在相对链接中省略后缀，因为GitHub有自己的方式来解析要使用的页面。

此外，GitHub Wikis在解析非维基链接时似乎使用了扁平的命名空间。尽管您可能在文件中使用文件夹，但路径似乎不起作用。

.Main 1
[%collapsible]
====
. link:./subitem1[Subitem 1]
. link:./subitem2[Subitem 2]
====
.Main 2
[%collapsible]
====
. link:./subitem3[Subitem 3]
. link:./subitem4[Subitem 4]
====

- Dennis

Answer 8

GitHub会在AsciiDoc页面中自动生成文档目录，但不会在Markdown中生成。不过这很容易做到。将Markdown转换为AsciiDoc也很容易，它们非常相似。

1. 将文档类型更改为AsciiDoc而不是Markdown。
2. 在文档开头插入:toc:。

我制作了一个演示存储库，其中演示了嵌入Wiki页面而不是侧边栏的自动生成TOC。以下是结果：

- Dogweather

---

这个不起作用。 - Steven Dake

@StevenDake 我制作了这个演示存储库，展示如何实现它：https://github.com/dogweather/github-wiki-toc-demo/wiki - Dogweather

@StevenDake 我创建了这个演示仓库，展示了如何实现它：https://github.com/dogweather/github-wiki-toc-demo/wiki - Dogweather