Tortilla

Tortilla is a framework for building tutorials based on git and NodeJS which will help you create AWESOME tutorials and upload them to any git-host which supports markdown rendering, like GitHub. Tortilla operates by simply wrapping an existing git project, thus providing you with some advanced git functions dedicated to create the most perfect and most beautiful tutorial in the world. In addition, Tortilla is easily accessible through a CLI, making it very convenient to use.

What's the advantages of using Tortilla over writing a simple blog-post?

• The code and the instructions will always stay correlatively updated.
• You can reference code snippets directly from the instructions.
• You can use template-helpers to write complex instructions with minimal efforts.
• You can take advantages of most git features like creating commits, tags and branches.
• You can use neat features natively provided with the git host like reporting issues and opening pull requests.
• The tutorial is linked directly to your git host account.
• You can enjoy the great traffic of the git host.
• You can easily navigate through the project at any specific point of the tutorial.
• You can historicize different versions of your tutorial.
• You can compare different versions of the tutorial and see the differences.
• The list goes on and on and on...

Tutorials for example:

• How to implement a game engine in JavaScript and build a Tron-style game
• How to build a Whatsapp-clone using Ionic 2 CLI and Meteor

If you're not familiar with Tortilla I recommend you to go through the this README.md file since it contains everything you have to know about Tortilla in order to use it.

Tutorial Structure

See:

• steps
  • sub-steps
  • super-steps
• manuals
  • translations
  • template-helpers
• releases
  • release-tags
  • history-branches

Steps

Each commit should represent a single step in the tutorial, using the following message template:

Step (step index): (step description)

Here's a list of commits for example:

Step 2: Add todo-list
Step 2.3: Add todo-list controller
Step 2.2: Add todo-list view
Step 2.1: Add todo-list model
Step 1: Bundling
Step 1.3: Install the necessary packages for Webpack's build
Step 1.2: Add Webpack build to gulp tasks
Step 1.1: Create a basic Webpack config
How to create a todo list

As you can see, some of the commits represent a sub-step (e.g. step 1.1, 1.2) and some of them represent a super-step (e.g. step 1, 2); Together they form a whole single step. Note that the only exception is the root commit whose message can be whatever you'd like (will most likely be something which describes the tutorial), but the rest of the commits must follow these rules, otherwise you will encounter some unexpected behaviors.

Credit goes to @stubailo who originally came up with the commit templates concept.

Related CLI: tortilla-step CLI

Sub Step

A sub-step is a small portion of the whole step. Each sub-step should usually represent a small change which should be followed by an explanation in the tutorial. Sub-steps should be sorted by their chronological order; Sub-steps which assemble the same step should have the same super index, and a consecutive sub index separated by a period (e.g. 1.1, 1.2).

Super Step

A super-step should always come at the end of each step, and should be represented with a single index (e.g. 1, 2). The super-step should add a manual file which goes through the implementation of the associated step.

Manuals

Manuals are markdown files which should contain some handy instructions regards the implementation of each step in the tutorial. The manuals are located under the .tortilla/manuals directory, and are separated into 2 directories - templates and views. When writing manuals, we should never touch the views files, because they should be auto-generated by Tortilla's CLI. The templates directory, as the name suggests, should contain manual templates. Just so you can get the idea, here's an example of a .tortilla/manuals directory structure:

.tortilla/manuals
├─ templates
│  ├ root.tmpl
│  ├ step1.tmpl
│  ├ step2.tmpl
│  └ step3.tmpl
└─ views
   ├ root.md
   ├ step1.md
   ├ step2.md
   └ step3.md

The main difference between a manual template and a manual view is that templates are more simplified and will be most likely used for development purposes. They contain some handy template helpers we can be used to render complex markdown components, so our tutorial can be good-looking and easy-to-read, with minimum maintenance. As you can see in the files tree above, manual template files have an extension of .tmpl, unlike their belonging views which finish with an extension of .md. That's because the manual templates are not exactly markdown files, since they are packed with some extra syntactic abilities provided by Handlebars' simple yet powerful templating engine. Indeed, you can still use markdown's templating syntax, but just know that this is not a pure markdown we're talking about. The only template-view fs correlation exception is the root.tmpl file which should be mapped to the README.md file, so we can see a nice introduction for our tutorial when entering the repository. The root.md file is just a symbolic link to the main README.md file.

Note that manual templates shouldn't be written with a title, since it should be attached automatically when rendering the template's view using its belonging commit message. In addition, a navigation bar between steps should be appended at the end of the manual. For example, a root manual template which looks likes this:

- FOO
- BAR
- BAZ

And is matched with the commit message:

Les Trois Mousquetaires

Should result with the following view after rendering:

# Les Trois Mousquetaires

- FOO
- BAR
- BAZ

[{]: <helper> (navStep)

| [Begin Tutorial >](manuals/views/step1.md) |
|----------------------:|

[}]: #

Related CLI: tortilla-manual CLI

Translations

Manuals don't necessarily have to be written in English, and can be also be written in whatever language you'd choose. Translated manual templates are located under the templates/locales/your-language path, and their belonging views are localed under views/locales/your-language. Here's an example of a manuals directory with manuals which are translated into Hebrew (he):

.tortilla/manuals
├─ templates
│  ├ root.tmpl
│  ├ step1.tmpl
│  ├ step2.tmpl
│  ├ step3.tmpl
│  └ locales/he
│    ├ root.tmpl
│    ├ step1.tmpl
│    ├ step2.tmpl
│    └ step3.tmpl
└─ views
   ├ root.md
   ├ step1.md
   ├ step2.md
   ├ step3.md
   └ locales/he
     ├ root.md
     ├ step1.md
     ├ step2.md
     └ step3.md

Translations for step messages (and potentially other stuff) can be defined under the .tortilla/locales directory in a json file with the relevant language code (e.g. .tortilla/locales/he.json). Here's an example of a translation file which translates step messages:

{
  "step": {
    "root": "כיצד ליצור רשימת מטלות",
    "1.1": "יצירת קובץ הגדרות בסיסי ל Webpack",
    "1.2": "הוספת משימה של בנייה בעזרת Webpack לרשימת המשימות של gulp",
    "1.3": "התקנת החבילות הנחוצות בכדי שנוכל לבנות בעזרת Webpack",
    "1": "צרירת הפרוייקט",
    "2.1": "יצירת מודל למטלה יחידה",
    "2.2": "יצירת רשימת מטלות ויזואלית",
    "2.3": "יצירת רשימת מטלות לוגית",
    "2": "הוספת רשימת מטלות"
  }
}

Template Helpers

Template helpers are used when writing a manual file to make our lives a bit easier when it comes to formatting complex markdown components. The templates are rendered using Handlebars' templating, so I recommend you to go through its rules and syntax so you can be familiar with it, but just for the heck of demonstration, a manual template file which looks like this:

*Here's how we should use template-helpers*

{{{diff_step 1.1}}}

Should be rendered to:

*Here's how we should use template-helpers*

[{]: <helper> (diffStep 1.1)

#### Step 1.1: Demo commit

##### Added demo-file.js
\`\`\`diff
@@ -0,0 +1,3 @@
+┊ ┊1┊foo
+┊ ┊2┊bar
+┊ ┊3┊baz🚫↵
\`\`\`

[}]: #

🌟 Available {{view models}} 🌟

• step - The number of the current step.

• commit_message - The current commit message.

🌟 Available {{{template helpers}}} 🌟

• nav_step - A navigation bar between step manuals. Will present two buttons - "Previous step" and "Next step". This template helper may receives the following options:

  • prev_ref - The reference which we will be redirected to once pressed on "Previous step" button.
  • next_ref - The reference which we will be redirected to once pressed on "Next step" button.

• diff_step <step> - Will run git diff for the specified step's commit. This template helper may receives the following options:

  • files - A list of specific file paths separated by a comma (,) that we would like to present in our diff. The rest of the files in the diff will be ignored.

Releases

A Tortilla project may contain release tags which represent different versions of the tutorial in different time points. Here's a list of tags for example:

master@root@0.0.1
master@step1@0.0.1
master@0.0.1
master@root@0.1.0
master@step1@0.1.0
master@0.1.0
foo@root@0.0.1
foo@step1@0.0.1
foo@0.0.1

In addition, a stack of all the releases is available through history branches:

master-history
foo-history

Related CLI: tortilla-release CLI

Release Tags

A release tag should represent the tutorial at a specific state (e.g. step 2 of master branch) and time point (e.g. version 1.2.1). A release tag should contain the name of the branch, the step descriptor, if at all, and a semver version, separated with at (@) signs (e.g. master@step1@0.0.1, foo@0.1.0).

History Branches

The history is specific for a certain branch. Its name should end with history preceded by the branch name (e.g. master-history). Each commit in that branch represents all the changes made in a specific release, making the comparison between releases much easier (even if they have different roots!). Here's an example of a commits list in a history branch named master-history:

master@1.0.0: Add favorites page
master@0.0.2: Update step 2
master@0.0.1: Initial tutorial creation

Quick Startup

First you will need to install Tortilla's CLI tool:

$ sudo npm install tortilla -g

Once you have it installed you can go ahead and create a new Tortilla project:

$ tortilla create my-tutorial -m "How to create my app"

This command will initialize a new Tortilla project called my-tutorial with an initial commit message of How to create my app.

After uploading this project and cloning it, be sure to initialize Tortilla so it can work properly:

$ git clone git@github.com:John/my-tutorial.git
$ tortilla init my-tutorial

A manual page for the usage of Tortilla's CLI tool can be brought any time by typing the following:

$ tortilla --help

For further information, I'd recommend you going through the CLI section.

CLI

See:

• tortilla
  • tortilla-manual
  • tortilla-release
  • tortilla-step
  • tortilla-strict

tortilla CLI

command: tortilla create [name]

Creates a new Tortilla project with the provided name.

• option: -o, --output [path] - The output path of the newly created project.
• option: -m, --message [message] - The created project's initial commit's message.
• option: --override - Override project directory if already exists.

command: tortilla init [name]

Initializes Tortilla essentials in the provided project.

tortilla-manual CLI

For more information see the manuals section.

command: tortilla manual render [step]

Renders specified manual view.

• option: --root - Render root manual (README.md).
• option: --all - Render all manuals.

tortilla-release CLI

For more information see the releases section.

command: tortilla release bump <type>

Bumps the current release of the tutorial. This will create some new release tags accordingly and will update the associated history branch. The provided type represents a semver version type (major, minor and patch) we would like to bump.

• option: -m, --message [message] - A message describing the newly created release. If not provided, and editor will be opened instead where we can type a full document.

command: tortilla release current

Prints the current release.

command: tortilla release diff <sourceRelease> <destinationRelease>

Runs git diff between 2 specified releases. This will also be able to run the operation between 2 different releases which are completely different from their root! You can also provide this command with some additional native git-diff options.

tortilla-step CLI

For more information see the steps section.

command: tortilla step push

Pushes a new step. Staged files will be committed along with this step.

• option: -m, --message [message] - A message describing the newly created step.

command: tortilla step pop

Pops the most recent step. This will completely discard the step's changes.

command: tortilla step tag

Mark this step as finished and move on to the next one. This will increase the index of the super-step and zero the index of the sub-step.

• option: -m, --message [message] - A message describing the newly created step.

command: tortilla step edit [step]

Edits the specified step/s. This will enter rebase mode where the step's hash is at. Once finished editing, you may proceed using git-rebase commands.

• option: --root - Edit the root step (initial commit).

command: tortilla step reword [step]

Rename the specified step's commit message.

• option: -m, --message [message] - The new message of the reworded step. If not provided, and editor will be opened instead where we can type a full document.

tortilla-strict CLI

Strict mode determines whether Tortilla's git-hook validations are enabled or disabled. It's highly recommended to leave it on, since you might accidentally digress from Tortilla's strict project rules.

command: tortilla strict get

Prints whether strict mode is enabled or disabled.

command: tortilla strict set <mode>

Sets strict mode. Provided mode must be either a truthy value (e.g. 1, true) or a falsy value (0, false).

License

MIT