CSI - Updating Documentaion

Formatting of this site

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

Tags: internal
Edit me