owasp-td-jekyll

This is a jekyll theme meant to be used as a documentation site as opposed to a blog, specifically being designed for OWASP Threat Dragon. It is opinionated on the file structure of your documentation for breadcrumbs to work. An example documentation file directory:

|---- environment (group)
|-------- page_1.md 
|-------- page_2.md
|-------- page_3.md
|---- tools (group)
|-------- tool_1.md
|-------- tool_1.md
|---- macos (group)
|-------- page_1.md
|---- windows (group)
|-------- page_1.md
|---- linux (group)
|-------- page_1.md

This theme is based on (Mike Goodwin's original Threat Dragon documentation site)[https://github.com/threatdragon/threatdragon.github.io/tree/original]

• Document the theme using github pages (and this theme)
• Document using bootstrap classes

Add this line to your Jekyll site's Gemfile:

gem "owasp-td-jekyll"

And add this line to your Jekyll site's _config.yml:

theme: owasp-td-jekyll

And then execute:

$ bundle

Or install it yourself as:

$ gem install owasp-td-jekyll

Install the gem Ensure your pages are structured as group/page.md Add your config:

title: OWASP Threat Dragon

theme: owasp-td-jekyll

brand: OWASP Threat Dragon
faviconUrl: /assets/images/favicon.ico

search:
  text:
  tooltip: Search documentation

theme_toggle:
  text:
  dark_tooltip: Switch to dark mode
  light_tooltip: Switch to light mode

header_links:
  - tooltip: Try the web app
    fa_class: fa fa-flask
    url: https://www.threatdragon.com/#/

  - tooltip: Download the desktop app
    fa_class: fa fa-cloud-download-alt
    target: _blank
    url: https://github.com/OWASP/threat-dragon/releases

  - tooltip: Visit us on GitHub
    fa_class: fab fa-github
    target: _blank
    url: https://github.com/OWASP/threat-dragon


nav:
  categories:
    - name: Development
      groups:
        - name: Environment
          fa_class: fas fa-layer-group
        - name: Contributing
          fa_class: fas fa-user-ninja
    - name: Threat Modeling
      groups:
        - name: Modeling
          fa_class: fas fa-project-diagram
        - name: Icons
          fa_class: fas fa-icons

logo_src: assets/images/threatdragon_logo_image.svg
homeLinks:
  - relative_url: something
    description: This is my description.  There are many like it, but this one is mine.
    fa_class: fas fa-project-diagram
  - relative_url: something_else
    description: This is my description.  There are many like it, but this one is mine.
    fa_class: fas fa-user-ninja

The sidebar is used as the primary navigation for the site, unless it is on a smaller device. The navigation is built from a combination of properties provided in your _config.yaml as well as having the group and nav_order properties set in your (front matter)[https://jekyllrb.com/docs/front-matter/]

Config for the sidebar, to be put in your _config.yaml:

Example nav in _config.yaml

nav:
  categories:
    - name: Cat 1
      groups:
        - name: My Dropdown
          fa_class: fas-fa-layer-group

Example page:

---
title: Users
path: modeling/users
group: Cat 1
layout: page
nav_order: 0
---
# Users
Some more text goes here

The home page layout is a special layout. Text is put into the jumbotron, with an optional image (if configured in the config). Actions may also be configured for this using the _config.yaml. This was set up with the idea of only ever having a single home page.

Home Options (to be set in your _config.yaml):

Example home page:

---
layout: home
title: Home
path: /
---

# Hello, world!
This is some content I got going on here, thanks for swinging by...

The page layout is the standard layout to be used. Example page:

---
title: Users
path: modeling/users
group: Icons
layout: page
nav_order: 0
---
# Users
Some more text goes here

Breadcrumbs rely on the file structure of your documentation to be as follows: category/group/page.md. Please see the top of the readme for a full example tree.

The theme includes a built-in documentation search field in the top navigation. It uses a Jekyll-generated JSON index at /assets/search.json and a small native JavaScript controller, so there are no additional third-party frontend dependencies to install or update.

Pages are indexed automatically when they have a title. To exclude a page from search, set this in its front matter:

search: false

Bug reports and pull requests are welcome on GitHub at https://github.com/lreading/owasp-td-jekyll. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

To set up your environment to develop this theme, run bundle install.

To run the same accessibility baseline locally that CI uses, also install the Node dev dependency and run:

npm install
npm run check:accessibility

That command rebuilds the Jekyll site and validates the generated HTML in _site with html-validate, giving a lightweight accessibility-focused baseline on pull requests and release builds. The check runs through plain npm scripts rather than a Bash wrapper, so it is friendlier to Windows contributors as well.

Your theme is setup just like a normal Jekyll site! To test your theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

The repo also includes a Development Fixtures sidebar category in _config.yaml plus example pages under testing/ to exercise both a single-page group and a multi-page dropdown group during local verification.

When your theme is released, only the files in _layouts, _includes, and assets tracked with Git will be bundled. To add a custom directory to your theme-gem, please edit the regexp in owasp-td-jekyll.gemspec accordingly.

The theme is available as open source under the terms of the Apache 2.0 License.