How To Format a Tutorial

Before publishing tutorial content on Debuntu, please read the following guide in order to learn how to format and submit your content.

By doing so, your tutorial will properly get integrated into Debuntu and make article browsing an enjoyable experience for the users.

1. Getting started!

Debuntu provides an article skeleton in both .zip [1] or .tar.gz [1] format which you can download.

Unpack this archive somewhere in your workspace, and start editing the file debuntu-articles-skeleton/index.html with your favorite text editor.

Your content will be nested in between the  and  HTML tags.

From now on, you will be able to preview your article simply by opening the file index.html with your favorite web browser (Firefox is a good bet ;-) ), and reloading the page any time you want to check the changes you made.

2. Formatting

2.1. Heading

Heading should be formatted using the <h2>...</h2>, <h3>..</h3>, <h4>..</h4>, please do not use the <h1>..</h1> tags as those are used for the tutorial's main title.

Headings will look like:

heading h2

heading h3

heading h4

heading h5

2.2. Standard Text

Normal text paragraph should be enclosed between <p>...</p> tags. Please do not use tags like <font>.

Paragraph:

<p>A paragraph example</p>

will look like:

A paragraph example

If you want to output < (less than) or > (greater than) symbol, you have to use HTML special characters < (less than) or > (greater than)

2.3. Command Line Content

To format shell command line, please use the CSS class .shell .

<p class="shell">ls -alh</p>

will look like this on debuntu:

ls -alh

2.4. File Content

Content of files should be but in between <pre>..</pre> preformatted tags and using the CSS class .file .

For instance, if you want to show the content of file /etc/apache2/httpd.conf to users, you will have to use:

<pre class="file">
# This is here for backwards compatability reasons and to support
# installing 3rd party modules directly via apxs2, rather than
# through the /etc/apache2/mods-{available,enabled} mechanism.
#
#LoadModule mod_placeholder /usr/lib/apache2/modules/mod_placeholder.so
</pre>

This will look like this on debuntu:

# This is here for backwards compatability reasons and to support
#  installing 3rd party modules directly via apxs2, rather than
#  through the /etc/apache2/mods-{available,enabled} mechanism.
#
#LoadModule mod_placeholder /usr/lib/apache2/modules/mod_placeholder.so

2.5. Technical terms, File Names, Protocols...

If you want to highlight Linux system keywords such as file names, protocols, technical terms... in a text paragraph, you can use the CSS class .tech inside <span>..</span> tags.

Here is an example:

<p>Now edit <span class="tech">/etc/apache2/apache2.conf</span> and add:</p>

will look like this:

Now edit /etc/apache2/apache2.conf and add:

2.6. Tip, Important and Warning Notes

You can highlight messages by using

If you want to inform users about a tip or a warning note, you can use the CSS classes .tip, .important and .warning.

For instance, the following codes:

<p class="tip">This is a tip note!</p>

will produce:

This is a tip note!

<p class="important">This is an important note!</p>

will produce:

This is an important note!

and:

<p class="warning">This is an warning!</p>

will produce:

This is a warning!

2.7. References

If you used other people's materials to make your article, it is a good idea to point them out at the end of your article. To do so, you can use the CSS class .reference

Please, use the title="xxx" and target="_" arguments in <a> tags. Title as the effect of displaying a tooltip when a user leave leave is cursor over the link. target="_" make the link open in a new window.

<p class="reference">
1. <a href="http://www.debuntu.org" title="debuntu tips and tricks" target="_">debuntu</a> debian/ubuntu tips and tricks
2. <a href="http://httpd.apache.org" title="apache web server" target="_">apache</a> apache web server
</p>

will look like this on debuntu:

1. debuntu [2] debian/ubuntu tips and tricks
2. apache [3] apache web server

3. Publishing Content

There is two different ways of publishing articles: story [3] and book page [3].

A story [3] is a single page article, use this if you believe your article will be made of only one page.

A book page [3] is used for multiple pages articles. If you think your article is too big to get on a single page, you will need to create a book.

To be able to create a story or an article, you need to be logged in.

3.1. Creating a Story

Using the menu on the left side, click on story [3]. You will then get to a page with a textarea where you will enter your tutorial.

Enter the story title and select one or more categories from the categories list. Note that you can select more than on category by keeping the Ctrl key pressed while selecting items from the list with your mouse.
(If you think some categories are missing, please feel free to contact [3] me so I can add them)

In the Body textarea copy the HTML code, the one between the  and  tags, from your text editor and paste it into the textarea body zone.

Before submitting your article, you can preview it by using the preview button at the bottom of the form. Once you believe it is all good, submit it.

3.2. Creating a Book Page

A book is designed to make articles over more than one page. There is basically two different kind of book pages: the parent page, which is the first page of your book, and children pages which are the other pages related to the book created in the first place.

3.2.1. Creating the first page

To create a book, you need to be logged in. Then, using the menu on the left side, click on book page [3]. You will then land on a page with a textarea in which you are going to enter the first page of your tutorial.

Enter the title of the article in the Title box
In the Parent zone, choose <top-level>
Choose the categories your article belongs to in the Category list. You can select more than one item by holding the Ctrl key pressed and click on different items
In the Body textarea, copy and paste the content of the first page from your text editor. Only the part between the  and  tags

You can now Preview and then Submit your first article page.

3.2.2. Subsequent pages

To add new page to your article, use the book page [3] link from the menu on the left side and:

Enter the same Title as your first book page plus -- page X, that is -- page 2 for the second page, -- page 3 for the third one and so on.
In the Parent zone, choose the first page of the book.
In the Category list choose <none>
For the Body copy the content like for the first page

4. What's next?

After submitting your article, your tutorial won't show up directly on Debuntu. Your article will be reviewed in order to check that formatting, content are fine. Once this is done, your article will be made public and will be promoted to the front page.