Skip to content

Latest commit

 

History

History
 
 

doc

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Drake Website - Jekyll Information

Directory Structure

Here is the directory structure relevant to Jekyll:

doc/
├── assets/ - Static assets.
│   ├── css/
│   └── js/
├── doxygen_cxx/ - C++ API reference.
├── images/ - Images.
├── _includes/ - Jekyll include components (via Liquid). Can render Markdown.
├── _layouts/ - Jekyll HTML layouts. Can *not* render Markdown.
├── _pages/ - Jekyll collection: Add'l root-level pages. Can render Markdown.
├── pydrake/ - Python API reference.
├── _release-notes/ - Jekyll collection: Index of versioned releases.
├── styleguide/ - Drake Style Guide external.
├── third_party/ - Third party assets.
└── index.md - Home page.

Relevant Documentation

For documentation regarding client-side technology:

Tools for debugging client-side (HTML, CSS, JavaScript):

All server-side concepts are those supported by Jekyll:

Caveats

Using Markdown in HTML tags

Kramdown has the useful feature of being able to use the attribute @markdown="1". However, it can make things a little weird with indentation, so be careful and preview often!

For more information: https://kramdown.gettalong.org/syntax.html#html-blocks

Table of Contents

There are some solutions to generating TOC's, with some drawbacks:

Use Kramdown's {:toc} feature.

This is what we use. However, due the order in which Jekyll parses things, we cannot automagically "surround" page contents without doing so explicitly.

However, it's not that bad. :shrug:

Here's an example patch of adding TOC to a page:

diff --git a/example.md b/example.md
index f33a459..51ba7a4 100644
--- a/example.md
+++ b/example.md
@@ -1,7 +1,11 @@
 ---
 title: Example Page
+layout: page_with_toc
 ---
 
+{% include toc.md %}
+<article class="markdown-body" markdown="1">
+
 # Towards the Start
@@ -39,3 +43,5 @@ # Towards the End
 I have some nice content here.
+
+</article>

Use another plugin