CSI - Updating Documentaion
Editing Documentation sidebar menu navigation
Documentation menu content is managed in the osi-csi/documentation repository
Sidebar menu navigation is stored in GitHub at : documentation/_data/sidebars/main_sidebar.yaml
This file defines the structure of the sidebar menu in the CSI documentation site. It defines how the menu item will appear in the sidebar and references the HTML filename linked in the sidebar
NOTE : The YAML metadata for the menu option must match the corresponding YAML data in the destination file, or the page will not render.
Page Rendering
Markdown files (with .md extensions) are rendered into HTML as content is updated. Typically, updates will be added in a branch, which is later merged with the master branch. In order to see the effect of changes in the branch, reference that documentation through the appropriate subdirectory in the branch directory :
https://csi-docs.oit.ncsu.edu/branch/
Example
In this example :
- The title of this content in the main documentation menu is title.
- The output tag defines the type of content, in this case web.
- The folderitems tag indicates that the following items will be in the subdirectory below “Monitoring”
- The url defines the HTML address of that particular page
- The tags field allows definitions of search tags (does not work yet)
- title: Monitoring
output: web
folderitems:
- title: Overview
url: /monitoring-overview.html
output: web
- title: Problems
url: /monitoring-problems.html
output: web
NOTE: the url content must match the permalink in the frontmatter of the file of the linked content. The title names in the sidebar file and the content file do NOT have to match. The hierarchy of the files in GitHub is irrelevant (though I would keep it as organized as possible)
The YAML code at the beginning of the Overview page (at documentation/pages/monitoring/monitor-overview.md) is called the “frontmatter” (delimited by 3 dashes), and it looks like this :
---
title: Monitoring/Paging Overview
toc: true
keywords:
tags: []
permalink: monitoring-overview.html
summary: >
__summary of page__
---
note that the permalink tag matches the url tag in main_sidebar.yaml
Edit me