Team:Cologne-Duesseldorf/Wiki-Tutorial

Wiki Tutorial

Welcome to our wiki coding tutorial. We know that many teams struggle to set up their wiki so we decided to write a guide to help you get started. Large parts of it are based on the w3schools HTML and CSS tutorials. If we left anything unclear you can probably find a solution in no time there, otherwise feel free to contact us.

HTML

Basics

A website might not look like it, but it is basically a text document with some additional styling. The following example shows the minimal website:

		  
<!DOCTYPE html>
<html>
<head>
</head>
<body>
</body>
</html>
		  
		

The <!DOCTYPE html> declaration states the type of the document, in this case HTML5, just like a file extension. The <html> and </html> tags surround all the code that you can write. Inside the <head></head> tags you can import CSS stylesheets, set the display name of the website and other meta information. Inside the <body></body> element you write the actual visible page content. Since the doctype and page titles are handled by mediawiki it is not necessary to include them in your wiki page.

The <!DOCTYPE html> declaration states the type of the document, in this case HTML5, just like a file extension. The <html> and </html> tags surround all the code that you can write. Inside the <head></head> tags you can import CSS stylesheets, set the display name of the website and other meta information. Inside the <body></body> element you write the actual visible page content. Since the doctype and page titles are handled by mediawiki it is not necessary to include them in your wiki page.

Basic Layout

To understand how to set up your wiki you first have to grasp some basic html and CSS concepts. Modern websites are usually build with div-containers, which basically are rectangles. These containers can be stacked, next to each other or nested inside another. Html elements are constructed using opening angle brackets <> and are usualy closed with closing angle brackets </>. They can be styled using either the class attribute <div class=""&gt or using an id <div id=""&gt, the difference between those two being , that each id tag should only be used once per page, while the class tag can be used as often as liked. You can also style the divs using the style inline method <div style=""&gt, but this is not recommended, since you would have to do this for every single element over again. The following code snippet shows the nesting of containers, with a little styling added (not shown).

		    
<div>
  <div>
    <div>
      <p>Test</p>
    </div>
  </div>
</div>
		    
		  

Test

The Wiki Layout

Just alike the example above the wiki already provides several levels of layout that you can access: #globalWrapper, #content, #HQ_page, and #bodyContent. While you could just nullify the styling of these divs and build your page backbone with your own divs I highly recommend actually overwriting them, as this gives you the possibility to build your wiki page backbone in a way that your other team members cannot overwrite it by accident. We will cover how in the CSS section of this post.Note that this page also has our teams wiki styling, so that some elements might look different when you are trying them out.

HTML elements

Headings

Just like in your favorite text editor, html comes with multiple levels of headings.

		      
<h1>Heading 1</h1>
		      
		    

Heading 1

		      
<h2>Heading 2</h2>
		      
		    

Heading 2

		      
<h3>Heading 3</h3>
		      
		    

Heading 3

		      
<h4>Heading 4</h4>
		      
		    

Heading 4

		      
<h5>Heading 5</h5>
		      
		    
Heading 5
		      
<h6>Heading 6</h6>
		      
		    
Heading 6

Text

Paragraphs

Whenever you are writing vanilla text, you should use the paragraph element <p>. Note though, that newline characters of text that you copy inside this tag are omitted. If you want a linebreak between two chunks of text you can either insert the two texts in seperate paragraph elements or use the line break element <br>. Note that br does not need a closing tag. Dependeing on your styling the paragraphs might have some margin or padding, thus increasing the distance between the two paragraphs when using <p> instead of <br>.

		      
<p>
  Paragraph one
  <br>
  Paragraph two
</p>
		      
		    

Paragraph one
Paragraph two

		      
<p>
  Paragraph one
</p>
<p>
  Paragraph two
</p>
		      
		    

Paragraph one

Paragraph two

Formatted text

If you want to emphasize certain elements of your paragraphs you can do it by using several inline elements, each of which you can style to your liking.

		      
<em>Emphasized text</em>
<strong>Strong text</strong>
<code>A piece of computer code</code>
<samp>Sample output from a computer program</samp>
<kbd>Keyboard input</kbd>
<var>Variable</var>
<mark>Mark</mark>
<cite>Cite</cite>
<dfn>Definition</dfn>
<sup>Higher</sup>
<sub>Lower</sub>
<small>Small text</small>
<del>Deleted text</del>
<ins>Inserted text</ins>
<abbr title="abbrevation explanation">abbrevation</abbr>
		      
		    

Emphasized text
Strong text
A piece of computer code
Sample output from a computer program
Keyboard input
Variable
Mark
Cite
Definition
Normal, Higher
Normal, Lower
Normal, Small text
Deleted text
Inserted text
abbrevation

Links

		      
<a href="http://2017.igem.org/Team:Cologne-Duesseldorf">
  Link to our wiki home page
</a>
		      
		    

Images

Images can be embedded using the <img> tag. Note that there is no closing </img> tag.

		      
		<img src="http://2017.igem.org/wiki/images/0/0d/T--Cologne-Duesseldorf--artico-logo-cities.svg">
		      
		    

Lists

Unordered List

		      
<ul>
  <li>Element 1</li>
  <li>Element 2</li>
  <li>Element 3</li>
</ul>
		      
		    
  • Element 1
  • Element 2
  • Element 3

Ordered List

		      
<ol>
  <li>Element 1</li>
  <li>Element 2</li>
  <li>Element 3</li>
</ol>
		      
		    
  1. Element 1
  2. Element 2
  3. Element 3

Nested List

		      
<ol>
  <li>Element 1</li>
  <ul>
    <li>Element 2</li>
  </ul>
  <li>Element 3</li>
</ol>
		      
		    
  1. Element 1
    • Element 2
  2. Element 3

Tables

		      
<table>
  <thead>
    <tr>
      <th>Head 1</th>
      <th>Head 2</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Data 1</td>
      <td>Data 2</td>
    </tr>
  </tbody>
</table>
		      
		    
Head 1 Head 2
Data 1 Data 2

Semantic Elements

header, footer, article, section

CSS

After we have covered some HTML, let us take a look at the second language we need to build a wiki. While HTML provides the structural backbone and content of the page, CSS is used to style it. As written before, there are three ways to write CSS code: Inline, directly onto the element, in the header of the page and in a seperate file. Since you want to use the same styling on every wiki page, I strongly suggest to keep the css file seperate and to import it at the top of your page. In mediawiki the easiest way to do that is to create a seperate page, for example http://2017.igem.org/Template:YourTeamName/css and then import it by writing {{Template:YourTeamName/css}} at the top of the page you are writing, before the <html> tag. The backbone of the css template page would look like the following:

		  
<html>
  <head>
    <style>

    </style>
  </head>
</html>
		  
		

Basics

CSS code is structured in the following way: Say we have heading that is defined in our document as <h1>Heading</h1>. Then we can change the font size of this heading via h1 {font-size: 20px;} in our CSS file. The syntax of this is a little different to what we have seen before, so let's dissect it a bit. The h1 part is the selector of the CSS rule. In this case it is the element selector, selecting every h1 element on the page. There are also the id #yourIdName and class .yourClassName selectors. They can for example be used on a div element, if it has the respective attribute <div class="yourClassName"> and/or <div id="yourIdName">. The actual properties of the element are changed inside the curvy brackets {font-size: 20px;}. The syntax here is property: value;. The semicolon at the end can be omitted on the last property or if only one property is stated, but since it doesn't hurt to have it at the end I'd advice you to always set it, to avoid mistakes.

A large list of CSS properties can be found here.

There is also a whole lot more of selectors. I found the following ones to be very important, but depending on what you are trying to accomplish it is well worth taking a look at the page linked before.

Selector Function
* All elements
element1 element2 All element2 that are inside element1
element1,element2 Both elements
element:hover The element while your mouse is hovering over it

Also note that CSS has a certain order on how elements are styled if they are given multiple contradictory statements. The most important level of CSS is the inline-style you give your elements. Descending from that the level depends on the specificity. So #bodyContent h1 will overwrite the code of h1. This is very important, since the wiki already has some pre-configured styles, which are on a higher level. Not considering this can give you quite some headaches while searching for any bugs.

You can access the wiki style file through the source code of your page but since it is also minimized I formatted and copied it onto our wiki, so you can read it in a more human-readable format.

Box Model

In CSS elements can be seen as boxes with a content, an inside padding, a border and an outside margin.

		      
<div style="
margin:10px;
border:10px solid #149375;
padding: 5px;
box-sizing:content-box;">
    <p>DIV</p>
</div>
		      
		    

DIV

By default margin, padding and border are added to any width statement you make. If you don't want to constantly calculate the actual size of the elements, use box-sizing:border-box, as this will reduce the size of the content of the element in such a way that the width property is matched.

					
<div style="
margin:10px;
border:10px solid #149375;
padding: 5px;
box-sizing:border-box;">
		<p>DIV</p>
</div>
					
				

DIV

Tips

Here are a few quick code snippets that will probably make designing your wiki easier.

Border Box on all Elements

		  
		* {
		  box-sizing: border-box;
		}
		  
		

Images

		  
		img {
		  display:block;
		  max-width:100%;
		  margin:auto;
		}
		  
		

The display:block; property is needed for the usual positioning of the image, while margin:auto horizontally centers the image in its parent div. max-width:100% scales the image as large as possible, but doesn't scale it above the image's resolution. A quick word on image resolution by the way: scale them appropriately to the final size they need on your wiki, not larger. Loading a bunch of large images is very time consuming, especially mobile devices.

Media Queries

		  
		@media (min-width: 900px) {
		  body {
		    margin: 16px 0 0 0;
		  }
		  
		

When designing for multiple device sizes, which you really should, sometimes percentage based resizing is not enough and you might want to make bigger changes to the page layout. In that case media queries are usefull as they allow to set rules that are only applied in a certain range screen sizes. In the example a mobile-first approach was chosen and for screens wider than 900 px the changes are applied. If you want your design to be responsive to the screen size, don't forget to add <meta name="viewport" content="width=device-width, initial-scale=1"> to the head of your document.

Flexbox

		  
		.div {
		  display:flex;
		  flex-direction: row;
		  justify-content: center;
		  align-items: center;
		}
		  
		

Flexbox is a very convenient way to achieve proper vertical centering. It is also quite useful for shifting content when designing for multiple device sizes by using flex-direction: column;. Just keep in mind that in that case the direction of justify-content and align-items is reversed.