To contribute a tutorial, please first read the contribution guidelines. Then submit a pull request against this repository, using the directions below.
Play with Docker follows the Jeykll post naming convention. Place a new document in Markdown in the
/_posts directory with the following naming convention:
The date will be used for ordering the post on the front page, not for tracking the date published. We may change that portion of the file name at a later point to change the ordering.
Any supporting images should be placed in the
/images directory and referenced with
YAML Front Matter
Each post starts with a YAML Front Matter block. This tells the site information it needs to render the post correctly. Not just Jekyll but also the Play with Docker SDK. However, you don't need to know about Jekyll or the SDK to write a post, though. Just make sure that you start a post with the following text block:
--- layout: post title: "Title of Your Awesome New Tutorial" date: YYYY-MM-DD author: "@your-github-user-name" tags: [see tags below] categories: see categories below terms: ---
terms is optional, as it defaults to
layout: for layout, always use
title: the title that will go top of the tutorial
date: must match the date used in the file name
author: use your GitHub user name
tags: must be an array, such as
[linux, operations, webapp]. This will be used by Play with Docker to populate list of tutorials the front page. Always use lower-case.
categories: choose one of:
community. This will be used to place the post in the list of tutorials on the front page. Always use lower-case.
terms: an integer between 0 and 6. This is the number of terminal windows on the tutorial page. This will default to
1if you don't specify it. If you specify
0, there won't be any terminals.
0should only be used if you are giving overview content with no interactivity, or describing a hands-on tutorial that has to run on the reader's local machine or in a VM.
Formatting is pretty standard Markdown. Be aware that if you have one or more terminals, half the page will be taken up with the terminal windows. This is adjustable by the user but you should write as if it won't be shifted. Take a look at the Swarm mode introduction tutorial to see what this looks like, and the In-container Java Development: Netbeans tutorial to see what it looks like without a terminal.
You shouldn't need to use any CSS in your tutorials or change any of the CSS in the
Auto populating code in the terminal
The Play with Docker SDK allows us to auto populate code into the terminal. Code blocks are specified with triple backticks
``` on each end. With the addition of a
.termN after the open set of backticks, you can direct that code block to a specific terminal. For instance, to run code in the first terminal, you would add
.term1. For instance:
````.term1 docker swarm init --advertise-addr $(hostname -i) ````
You can write multiple lines as well as just one, and they will sequentially be added to the terminal. If you do not specify
termN clicking on the code block will not cause it to be placed in the terminal. This is useful if you want to show example code that someone would copy and paste into a file before running.
Linking to apps that run in a terminal
Any apps that run in a terminal and expose a port can be discovered for linking purposes. The pattern is:
For instance, if you wanted to link to a webserver running in terminal 2 at port 8080, you would use:
This is necessary because when you write the post you won't know in advance what the base URL of an individual session will be on Play with Docker. That will produce a URL such as this:
When you are ready, submit your PR against this repository. The Play with Docker team will evaluate it before merging it, and may require changes or close the PR at their discretion.