Modular Markdown



Developers are accustomed to writing code in a modular fashion. Modularity is achieved using distinct functions, files, and directories to partition code in meaningful ways. This approach typically improves code clarity and aids modifications and maintenance over time.

GitPitch supports this same modular approach for presentation markdown and associated image assets, settings, and custom css.


1. Learn By Example

This PITCHME.md markdown snippet:

## Modular Markdown Demo

---?include=meetup/intro/PITCHME.md

---?include=meetup/topics/PITCHME.md

---?include=meetup/call-to-action/PITCHME.md

Results in the rendering of a slideshow presentation that includes the following slides:

  • Every slide defined in the top-level PITCHME.md file plus
  • Every slide defined in the intro, topics, and call-to-action markdown files.

Any included markdown files can contain an unlimited number of slides using the standard slide delimiters and full GitPitch features.



2. The Modular Markdown Slide Delimiter

The include delimiter is used to import modular markdown content into a top-level PITCHME.md markdown file for a given presentation. The delimiter takes a relative path to any markdown file found within your repository. Paths must be relative to the root directory of the repository.

---?include=path/to/topic/PITCHME.md

The include delimiter can only be used in top-level PITCHME.md markdown file for a given presentation. Any markdown file that has been included can not itself use the include delimiter to include further files.



3. Example: Modular HTML5 Training Slideshow

The following example demonstrates a modular approach to delivering training course materials for an introduction to HTML5. The file and directory structure recognizes the inherently modular nature of the course content.

Let’s assume our HTML5 training course provides an introduction to the key HTML5 technologies: HTML, CSS, and JavaScript. We can use the following directory and file structure for our slideshow content in the repository:

.
├── PITCHME.md
|
├── PITCHME.yaml
|
├── common
│   ├── about
│   │   └── PITCHME.md
│   └── contact
│       └── PITCHME.md
|
└── training
    |
    └── topics
        |
        ├── css
        |   |
        │   ├── PITCHME.md
        |   |
        │   ├── selectors
        │   │   └── PITCHME.md
        |   |
        │   └── syntax
        │       └── PITCHME.md
        |
        ├── html
        |   |
        │   ├── PITCHME.md
        |   |
        │   ├── attributes
        │   │   └── PITCHME.md
        |   |
        │   └── tags
        │       └── PITCHME.md
        |
        └── js
            |
            ├── PITCHME.md
            |
            ├── callbacks
            │   └── PITCHME.md
            └── objects
                └── PITCHME.md

Slides for each major topic and sub-topic can be maintained within topic-specific PITCHME.md markdown files under the course/topics directory.

The top-level PITCHME.md in the directory structure can then use the modular markdown slide delimiter to merge all sub-topics into a comprehensive HTML5 training slideshow, for example:

# HTML5 Training Course

---?include=course/common/greeting/PITCHME.md

---?include=course/topics/html/PITCHME.md

---?include=course/topics/html/tags/PITCHME.md

---?include=course/topics/html/attributes/PITCHME.md

---?include=course/topics/css/PITCHME.md

---?include=course/topics/css/syntax/PITCHME.md

---?include=course/topics/css/selectors/PITCHME.md

---?include=course/topics/js/PITCHME.md

---?include=course/topics/js/objects/PITCHME.md

---?include=course/topics/js/callbacks/PITCHME.md

---?include=course/common/contact-me/PITCHME.md

Adopting this modular approach when managing slideshow content delivers all of the benefits typically associated with modular design: improved clarity, greater consistency, and simplified maintenance.

This modular approach to managing and maintaining slideshow content also lends itself perfectly to delivering Modular Slideshows.



4. Example: Modular Localized Slideshow Content

The following example demonstrates a modular approach to delivering localized slideshow content in order to deliver a single slide deck in multiple languages. The file and directory structure takes advantage of the inherently modular nature of language-specific versus language-independent slideshow content.

Let’s assume our goal is to create a slide deck that can be delivered in English, Spanish, French, and Japanese. We can use the following directory and file structure for our slideshow content in the repository:

.
├── PITCHME.yaml
|
├── assets
|
│   ├── css
│   │   └── PITCHME.css
|   |
│   └── img
│       ├── humor.gif
│       ├── logo.png
│       └── overview.jpg
|
└── slides
    |
    ├── en
    │   └── PITCHME.md
    |
    ├── es
    │   └── PITCHME.md
    |
    ├── fr
    │   └── PITCHME.md
    |
    ├── jp
    │   └── PITCHME.md
    |
    └── shared
        |
        ├── architecture.md
        ├── contact.md
        └── thank-you.md

Adopting this modular approach to managing slideshow content delivers all of the benefits typically associated with modular design: improved clarity, greater consistency, and simplified maintenance.

In this example, each set of language-specific slides are maintained within clearly differentiated language directories:

└── slides
    |
    ├── en
    │   └── PITCHME.md
    ├── es
    │   └── PITCHME.md
    ├── fr
    │   └── PITCHME.md
    └── jp
        └── PITCHME.md

While language-indepenent slides and common assets such as images, settings, and even custom css are maintained independently as follows:

.
├── PITCHME.yaml
|
├── assets
|
│   ├── css
│   │   └── PITCHME.css
|   |
│   └── img
│       ├── humor.gif
│       ├── logo.png
│       └── overview.jpg
|
└── slides
    |
    └── shared
        |
        ├── architecture.md
        ├── contact.md
        └── thank-you.md

To present this slideshow for a specific language, simply identify the chosen language [ en, es, fr, jp ] as a query parameter on the slideshow URL. For example, to present in French:

https://gitpitch.com/acmecorp/demo?p=slides/fr

Alternatively, to present the same slideshow presentation in Japanese:

https://gitpitch.com/acmecorp/demo?p=slides/jp

This modular approach to managing and maintaining slideshow content also lends itself perfectly to delivering Modular Slideshows.



5. Example: Modular Audience Specific Slideshow Content

The modular approach demonstrated by the Localized Slideshow Content example above can be used to deliver all kinds of slide decks that need to deliver custom variations of slide content for specific audiences.

For example, this same approach can be used to deliver a slide deck that introduces an API. Rather than Spanish, French, and Japenese specific slides, this same modular approach can be used to deliver Java, Elixir, and Go specific slides for the same API.

To present this slideshow for a specific programming language audience, simply identify the chosen language [ java, elixir, go ] as a query parameter on the slideshow URL. For example, to present at an Elixir conference or meetup:

https://gitpitch.com/acmecorp/api?p=slides/elixir