如何为GitHub页面生成JavaScript API文档

为其他语言生成API文档有很多很好的选择，但我还没有找到一个解决方案，用于在GitHub页面上托管JavaScript API。看起来我可以使用，但我需要创建一个输出Jekyll标记的自定义插件

我还希望代码URL链接到GitHub本身。我发现这样做会影响输出以更改链接，但我更喜欢一个更直接的选项，在那里我有更多的控制权

---

我是否必须创建自己的JSDoc插件，或者是否有一个更好的解决方案我错过了。人们用什么做这个？

我想这就是你想要的：

jsdox是一个简单的JSDOC3生成器。它从javascript文件中提取基于JSDOC3子集的文档标记，并生成标记文件

如果您熟悉，可以轻松地使用生成

.html

文档

• 用文档记录您的代码
• 用于内部生成代码文档
• 这还将以HTML格式输出源代码，并在文档中包含指向每个可公开访问成员的代码行的链接
• 您还可以通过使用JSDoc的

  @link

  指令控制链接：
  

  参见{@linkhttps://github.com/onury|我的GitHub配置文件}

请参阅下面的Gruntfile示例。
请注意，这支持所有

grunt.initConfig({
“jsdoc”：{
地区：{
src:['./src/core/mylib.js']，
选项：{
目的地：'./doc/html'
}
}
}
});

您可以使用

gruntjsdoc

运行此任务。或者，您可以添加

grunt contrib watch

插件，以便在每次文件更改时自动运行

模板和样式：

• 您可以随时使用CSS文件，并根据自己的喜好覆盖它
• 或者您可以使用基于引导的JSDoc3模板，该模板可以与

  GruntJSDOC

  一起使用

用于文档编制：

尽管本机支持它，但您不必将Jekyll用于GitHub页面。Jekyll实际上是为静态网站或博客设计的。但它可以删除降价文件。因此，我首先从代码via（还有一个Grunt插件）创建github风格的标记文件，然后相应地创建一个Jekyll项目

但是请注意，您需要做一些额外的工作来安装和配置Jekyll。这是一个好的开始

更新：

在回答了这个问题之后，我开始开发一个工具来轻松地构建文档。现在，它已经足够成熟了，可以在这里发布，看看你是否喜欢它。它叫

Docma的主要特点是：；它可以将JSDoc和Markdown文件解析为HTML文档，生成一个web应用程序，非常可配置，可与Github页面一起使用

请参阅，它也是用Docma构建的，托管在GitHub页面上

Docma生成SPA的示例屏幕截图：

---

虽然我已经有一段时间没有更新它了，但这是另一种选择。它只会生成HTML文件，您可以将这些文件提交到

gh页面

分支

我是大摇大摆的粉丝：&

它包含的不仅仅是API文档，所以对您来说可能有些过分，但它在编写API文档方面做得很好

正是您想要的。

试图简化它

• 在GitHub页面中生成输出Jekyll标记的API文档。
  带有

  {%raw%}

  标记的逃逸液体模板

  {% raw %}
     I want to be {{escaped}}.
  {% endraw %}
  

  参考：github/.com/Shopify/liquid/wiki/liquid for Designers#raw
  参考：jekyllrb/.com/docs/github pages/#项目页面
  创建两个分支，一个用于母版，一个用于gh页面， 主分支包含.md文件，gh页面包含静态生成的.html文件。 在本地计算机中：当前项目文件夹中的

  $jekyll build

  将生成到

  /\u站点

  上传到GitHub
  杰基尔
  • 主分支：github/.com/jekyll/jekyll
  • gh页面分支：github/.com/jekyll/jekyll/tree/gh页面
    fb/反应
    • 主分支：github/.com/facebook/react/edit/master/docs/docs/ref-01-top-level-api.md
    • gh pages分支：github/.com/facebook/react/blob/gh pages/docs/top-level-api.html
• 页面URL链接到GitHub文档本身。
  在

  \u布局

  文件夹中（html模板） 添加链接这是

---

我环顾了一下四周，我认为删除输出html是最简单的方法。我最终决定使用JSDox，它可以生成非常清晰的降价，并与。您可以在这里看到我是如何实现它的，以及最终结果：。谢谢你的建议。谢谢你，哈维。我简单地看了一下，但对我的口味来说似乎有点有限。我希望生成类似React文档的内容：。我不确定他们使用的是什么工具。尽管我之前发表了评论，但我最终还是决定使用JSDox，因为生成的标记非常干净，很容易剥皮。您可以在这里看到我是如何实现它的，以及最终结果：。谢谢哈维！