从子目录访问 Jekyll 集合文件

Question

我仍在学习 Jekyll，但我正在尝试移植我们的文档，以便人们在我们在产品中更新它们时可以访问我们的文档。理想情况下，我想让它尽可能无缝。我们的产品文档已经以 .md 格式布局，树形如下：

├── 01_Using_The_Dashboard
│   ├── 01_Dashboard_Overview.md
│   ├── 02_Widgets_Overview.md
│   ├── 03_Pre-built_Widgets.md
│   ├── 04_Creating_your_own_widgets.md
│   ├── 05_Search_Syntax.md
│   ├── 06_Dashboard_Import_Export.md
│   ├── images
│   │   ├── add-widget@2x.png
│   │   ├── controls@2x.png
│   │   ├── creating-search-widget@2x.png
│   │   ├── dashboard-edit@2x.png
│   │   ├── dashboard-selector@2x.png
│   │   ├── edit-widget-field@2x.png
│   │   ├── edit-widget-filter@2x.png
│   │   ├── edit-widget-modal@2x.png
│   │   ├── edit-widget-other@2x.png
│   │   ├── edit-widget@2x.png
│   │   ├── event-rate-widget@2x.png
│   │   ├── lastn-widget@2x.png
│   │   ├── notifications-widget@2x.png
│   │   ├── resize-widget@2x.png
│   │   ├── save-to-dashboard@2x.png
│   │   ├── search-results-widget@2x.png
│   │   ├── system-widget@2x.png
│   │   ├── tasks-widget@2x.png
│   │   ├── time-range-selector@2x.png
│   │   ├── time-range@2x.png
│   │   └── topn-widget@2x.png
│   └── index.md
├── 02_Creating_Triggers
│   ├── 01_Trigger_Page.md
│   ├── 02_Explanation_of_Actions.md
│   ├── 03_Trigger_Scripts.md
│   ├── images
│   │   ├── add-new-trigger.png
│   │   ├── add-note@2x.png
│   │   ├── execute-script@2x.png
│   │   ├── filters@2x.png
│   │   ├── issue-notification@2x.png
│   │   ├── query-bar@2x.png
│   │   ├── search-results@2x.png
│   │   ├── send-email@2x.png
│   │   └── system-settings@2x.png
│   └── index.md
├── 03_Alerts
│   ├── 01_Alerts_Overview.md
│   ├── 02_Automations.md
│   ├── 03_Trigger_Import_Export.md
│   ├── 04_Outgoing_Webhooks.md
│   ├── images
│   │   ├── add-new-trigger.png
│   │   ├── filters-hosts.png
│   │   ├── filters-severities.png
│   │   ├── outgoing_webhooks.png
│   │   ├── slack_alert.png
│   │   └── triggers.png
│   └── index.md
├── 04_Backend_Administration
│   ├── 01_Receiving_Syslog_Events.md
│   ├── 02_Sending_Email_From_The_Server.md
│   ├── 03_Archive_and_Restore.md
│   ├── 04_Server_Licensing.md
│   ├── 05_Using_TLS_Tunnels.md
│   ├── 06_Using_HTTPS.md
│   ├── 07_Backend_Configuration_Options.md
│   ├── 08_Backend_Search_Settings.md
│   ├── 09_Migrating_LogZilla_To_A_New_Server.md
│   ├── images
│   │   └── smtp.png
│   └── index.md
├── 05_Software_Notes
│   ├── 01_Development_Lifecycle.md
│   ├── 02_Release_Notes.md
│   ├── 03_LogZilla_VMWare_Image.md
│   ├── images
│   │   └── ticketflow.png
│   └── index.md
├── 06_Performance_Tuning
│   ├── 01_UDP_Buffer_Tuning.md
│   ├── 02_CPU_Frequency_Governers.md
│   ├── 03_VMWare_Performance.md
│   ├── 04_Filesystem_Performance.md
│   ├── images
│   │   └── vmware-disk-priority.png
│   └── index.md
├── 07_Receiving_Data
│   ├── 01_Receiving_SNMP_Traps.md
│   ├── 02_Cisco_IOS_Configuration.md
│   ├── 03_Receiving_Rsyslog_Events.md
│   ├── 04_Debugging_Event_Reception.md
│   ├── 05_Incoming_Webhooks.md
│   ├── 06_Receiving_Windows_Events.md
│   ├── images
│   │   ├── snare-001.png
│   │   ├── snare-002.png
│   │   ├── snare-003.png
│   │   └── snare-004.png
│   └── index.md
├── 08_Event_Correlation
│   ├── 01_Intro_to_Event_Correlation.md
│   ├── 02_Event_Correlation_Rule_Types.md
│   ├── 03_Sample_Rules.md
│   ├── 04_Correlating_Windows_Events.md
│   ├── images
│   │   ├── cisco-ec-mne.png
│   │   ├── cisco-ec-save.png
│   │   └── cisco-ec.png
│   └── index.md
├── 09_API
│   ├── 01_Using_The_API.md
│   └── index.md
└── template.html

我有几个障碍：

1. 当然是上面的结构
2. 我们的 md 文件没有使用 front matter，而是在 markdown 文件的顶部有 <!-- @@@title:Dashboard Overview@@@ -->。我可以做类似perl -i -pe 's/<\!-- @@@(title:)(.*?)@@@ -->/---\n$1 $2\n---\n/g' *.md 的事情，但不确定是否有更优雅的解决方案。
3. 还必须转换图像链接。在我们的文件中，它们是这样完成的：![Controls](@@path/images/controls.png)

有人可以建议一种方法，我可以使用它来使这个过程成为一个易于复制的过程，以便当我们更新我们的文档时，它们会在网站上自动更新？

Answer 1

1) 上面的结构应该没问题。我不会将它添加到“_posts”目录，而是直接添加到根文件夹。然后它应该生成如下文件：

01_Using_The_Dashboard/01_Dashboard_Overview.html

如果您对生成的永久链接不满意，您可以随时在 Frontmatter 中覆盖此设置。

2) 我不知道任何 $x2frontmatter 工具。据我所知，有一些东西可以从 wordpress 迁移。我认为您的 perl 解决方案可能是进行这种转换的最优雅的方式。还请考虑生成附加内容，例如“布局：页面”或类似内容，否则您必须在之后维护它。

3) 您可以使用基本 url 而不是 @@path。请参阅Parkers post。另请参阅variables section，其中可能包含其他有用的信息。

关于您的第四个问题，您似乎想知道如何自动部署更改。就像持续部署一样。有多种方法可以做到这一点。

1. 这是我当时写的一篇博客文章，用于使用 rsync, crontab and shell 自动部署。
2. 这里有一篇关于如何deploying to S3（包括资产）的更详细的博文。
3. 甚至可以选择部署到 GitHub。请参阅GitHub Pages 的文档。

我个人使用 CloudFront/S3 选项。