0.0
Low commit activity in last 3 years
No release in over a year
OWASP Threat Dragon documentation theme.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

~> 4.2
 Project Readme

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]

TODO

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

Installation

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

Usage

TLDR;

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

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

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

  - text: 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

General Config

Name Type Description
brand string The brand name to be used as the home link in the navbar
faviconUrl string The relative path to the favicon
header_links array Additional links to be added to the navbar (top, not sidebar)
header_links[0].text string The text of the link
header_links[0].fa_class string The font-awesome class to use for the dropdown. Use the full class, eg fab fa-github
header_links[0].url string The url to be used as the href preoprty on the anchor.
header_links[0].target string The target property for the anchor. Optional

Sidebar

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/]

Name Description Required
group Top level navigation on the sidebar is based on groups. Associate a page to a group. If only one page exists in a group, it is just a link as opposed to a dropdown. yes
nav_order The order in which to display the link in the navigation (within the group) no

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

Name Type Description
nav object The top-level navigation object
nav.categories array Categories to separate the different menu options. Used as a logical grouping
nav.categories[].name string The name of the category. Used for display purposes
nav.categories[].groups array The groups (dropdowns) to be used in the category.
nav.categories[].groups[].name string The name of the group. This should match the group tag used in your (front matter)[https://jekyllrb.com/docs/front-matter/]. If only a single page exists in a group, the nav will be a link as opposed to drop-down.
nav.categories[].groups[].fa_class string The font-awesome class to use for the dropdown. Use the full class, eg fas fa-user-ninja

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

Layouts

Home

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):

Name Type Description Required
logo_src string The location of your main brand logo no
homeLinks array The links/actions to display under the main content no
homeLinks[].relative_url string To be used as a link to a relative page yes
homeLinks[].description string Text to put under the icon no
homeLinks[].fa_class string The font-awesome class to use for the dropdown. Use the full class, eg fas fa-user-ninja yes

Example home page:

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

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

Page

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

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.

Contributing

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.

Development

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

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.

When your theme is released, only the files in _layouts, _includes, _sass 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.

License

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