Debian/Ubuntu Tips and Tricks

Debuntu

Debian/Ubuntu Tips and Tricks

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 or .tar.gz 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 <!-- Content BEGIN --> and <!-- This is were your content ends --> 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 &lt; (less than) or &gt; (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 debian/ubuntu tips and tricks
2. apache apache web server

3. 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.

Leave a Reply

XHTML: You can use these tags: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>