Formatting Articles: Difference between revisions

Revision as of 08:33, 18 May 2023

The following article will give you guidance on writing articles in the Grooper Wiki.

Creating a New Article

Step 1Step 2Step 3 and 4Step 5

1) Using the search bar, type the name of the article you wish to create.

2) If the article does not exist, you will see a message reading "Create the page "Article Name" on this wiki!" above the search results. Click the searched article's name in quotes to create it.

3) Use the text editor box to write your article. For more information on Mediawiki's markup formatting refer to the Writing Articles#Text Formatting - Markup Syntax section of this article.

4) Press the "Save Page" button at the bottom of the text editor to save the page.

5) If you need to edit your page further. Press the "Edit" button at the top of the article.

Text Formatting - Markup Syntax

Your article's text can be formatting using MediaWiki's markup. This is a syntax consisting of special characters, like asterisks, apostrophes and equals signs to do special things. For example, you can place a word in italics by placing a pair of apostrophies on both sides of the word, like ''this''.

Character Formatting

This is also referred to as "inline" formatting.

Format	You Type	You Get
Italics	''This is italic text''	This is italic text
Bold Text	'''This is bold text'''	This is bold text
Bold and Italics	'''''This is bold and italic text'''''	This is bold and italic text
Escape wiki markup	<nowiki>Don't use '''markup''' syntax</nowiki>	Don't use '''markup''' syntax

Sections

Section headers are useful to break up sections of information in your article. Sections and subsections are called out by pairs of equals signs on both sides of the sections name.

You Type	You Get
== Section Level 2 == === Section Level 3 === ==== Section Level 4 ==== ===== Section Level 5 ===== ====== Section Level 6 ======

Further Guidance

DO NOT use the "Level 1" section by typing a single equals sign on either side of the section name.

For example: = Level 1 =
- Don't do this! This is bad.

Level 1 is reserved for the page level for the article you are editing. Begin all subsections at Level 2

For example: == Level 2 ==
- Do this. This is good.

Do not type text on the same line of the section name. It will break the section.

You Type	You Get
== Section Name == Section info	== Section Name == Section info
== Section Name == Section info

Bullets and Indents

Bulleted lists can be created using the asterisk *.

You Type

You Get

Normal line of text.
* First bullet
* Second bullet
* Third bullet
** First sub-bullet
** Second sub-bullet
* Fourth bullet
** First sub-bullet
*** First sub-sub bullet

Normal line of text.

First bullet
Second bullet
Third bullet
- First sub-bullet
- Second sub-bullet
Fourth bullet
- First sub-bullet
  - First sub-sub bullet

Numbered bulleted lists can be created using the pound sign #.

You Type

You Get

Normal line of text.
# First bullet
# Second bullet
# Third bullet
## First sub-bullet
## Second sub-bullet
# Fourth bullet
## First sub-bullet
### First sub-sub bullet

Normal line of text.

First bullet
Second bullet
Third bullet
1. First sub-bullet
2. Second sub-bullet
Fourth bullet
1. First sub-bullet
  1. First sub-sub bullet

Lines can be indented using the colon character :

You Type

You Get

Normal line of text.
: First indented line
: Second indented line
: Third indented line
:: First twice indented line
:: Second twice indented line
: Fourth indented line
:: First twice indented line
::: First thrice indented line

Normal line of text.

First indented line

Second indented line

Third indented line

First twice indented line

Second twice indented line

Fourth indented line

First twice indented line

First thrice indented line

Bullets and indents can be mixed as well.

You Type

You Get

Normal line of text.
# First numbered line
# Second numbered line
# Third numbered line
#* Bullet under third numbered line
#: Indent under third numbered line
# Fourth numbered line
## Numbered bullet under fourth numbered line
##* First bullet under numbered bullet under the fourth numbered line

Normal line of text.

First numbered line
Second numbered line
Third numbered line
- Bullet under third numbered line
Indent under third numbered line
Fourth numbered line
1. Numbered bullet under fourth numbered line
  - First bullet under numbered bullet under the fourth numbered line

Notice the leftmost character of each line is always a pound sign #. If you break this pattern, you will start a new sequence of numbers.

You Type

You Get

Normal line of text.
# First numbered line
# Second numbered line
# Third numbered line
#* Bullet under third numbered line
* NEW SINGLE BULLET
# New numbered sequence line.
## Numbered bullet under new numbered line
##* First bullet under numbered bullet under the new numbered line

Normal line of text.

First numbered line
Second numbered line
Third numbered line
- Bullet under third numbered line

NEW SINGLE BULLET

New numbered sequence line.
1. Numbered bullet under new numbered line
  - First bullet under numbered bullet under the new numbered line

HTML Tags

Some HTML tags are allowed in MediaWiki.

Format	You Type	You Get
Fixed Width Text	Fixed width text is useful for calling out regular expressions, such as <code>[^\r\n\t\f]+</code>.	Fixed width text is useful for calling out regular expressions, such as `[^\r\n\t\f]+`.
Underlines	<u>This text is underlined.</u>	This text is underlined.
Strike-through	I want to <s>strike-through</s> a word.	I want to ~~strike-through~~ a word.
Blockquotes	Text before <blockquote>Blockquote</blockquote> Text after	Text before Blockquote Text after

Adding Images

There are two parts to inserting images into an article.

Uploading the file.
Using markup syntax to insert the image into an article.

Uploading Images

Step 1Step 2Step 3

1) On any page, find the "Tools" section in the left hand tool-bar.

2) Press the "Upload File" button.

3) On the following page, press the "Choose File" button and choose the image you wish to upload from the file browser.

4) Press the "Upload File" button at the bottom of the page to upload the image.

Adding the Image to an Article

The basic syntax for adding an image once it is uploaded is [[file:filename.extension]]

You Type	You Get
[[file:doge.jpg]]

Options

There are several options you can add to further format the image. Options are called out within the square brackets after the filename and extension, separated by a vertical bar character |. A single image can be modified using multiple options, each separated by a vertical bar. The syntax is as follows:

[[file:filename.extension|Option1|Option2|Option3]]

Format Options

Format	You Type	You Get
The Border option adds a thin grey border to the image.	text text text [[file:Goodboy.jpg\|border]] text text text	text text text text text text
The Frameless option creates a frameless thumbnail of the image.	text text text [[file:Goodboy.jpg\|frameless]] text text text	text text text text text text
Here, two format options are used Frameless and Border. Note the Frameless and Border options are rendered inline with the text. Adding a blank line before and after the image will put it on a new line.	text text text [[file:Goodboy.jpg\|frameless\|border]] text text text	text text text text text text
The Frame option adds a frame around the image. A caption can be added to the bottom of the frame as well. Frames are rendered as a right justified floating (rather than inline) block.	text text text [[file:Goodboy.jpg\|frame\|Insert caption here]] text text text	text text text Insert caption here text text text
The Thumb option creates a framed thumbnail of the image. Captions can also be added to thumbed images, which are also rendered as a right floating block.	text text text [[file:Goodboy.jpg\|thumb\|Who's a good boy?]] text text text	text text text Who's a good boy? text text text

Size Options

Images can be reduced in size or enlarged, with some caveats.

The Frame option may not be reduced or enlarged. It will ignore all size specifications
The Thumb and Frameless options can be reduced, but not enlarged more than the original size.

Images can be resized using the following options (Original file size is 800 x 400 pixels).

Format	You Type	You Get
Width adjustment in pixels.	[[file:Goodboy.jpg\|border\|250px]]
Height adjustment in pixels	[[file:Goodboy.jpg\|border\|x250px]]
Width and height adjustment in pixels. Note, this fits the image into box of the specified dimensions, but does not stretch or skew the image.	[[file:Goodboy.jpg\|border\|250x250px\|]]

Links

Internal Links

Links to articles within the wiki are called out with a double set of square brackets.

Links	You Type	You Get
Link to the Example Article page.	[[Example Article]]	Example Article
Link to an article, but display different text.	[[Example Article\|This is an example]]	This is an example
Characters after the brackets will be added to the hyperlink.	[[Example Article]]s	Example Articles
Avoid characters after brackets being added using the `<nowiki />` tag	[[Example Article]]<nowiki />s	Example Articles
Link to a section in this article.	[[#Links]]	#Links
Link to a section in another article.	[[Example Article#About]]	Example Article#About
Using the pipe to change the links name is especially helpful for section linking.	[[Example Article#About\|About]]	About

External Links

Links outside of this wiki can be "bare", or linked with no formatting. Or, they can be called out with a set of single square brackets to change the displayed text or show as a numbered annotation.

Links	You Type	You Get
Bare link	https://www.grooper.com	https://www.grooper.com
Annotation link	[https://www.grooper.com]	[1]
Change the link's displayed text	[https://www.grooper.com Grooper]	Grooper

Tables - Basic Formatting

Table formatting can be confusing. But, tables can be powerful additions to your articles. This is a very quick introduction.

Markup Character	Use
{\|	Table start - Always required at the begining of the table
\|-	Row start - Required to start a new row except for the first row. Wiki syntax always assumes the first row.
\|	New cell - Use a single "\|" for the first cell. Use a double "\|\|" for each new cell or another single "\|" if starting the cell on a new line (more on this later).
\|}	Table end - Always required at the end of the table.

If you want to create a table with three columns and three rows, the table would look as follows

{|
|Header 1||Header 2||Header 3
|-
|Row 1 - Cell 1||Row 1 - Cell 2||Row 1 - Cell 3
|-
|Row 2 - Cell 1||Row 2 - Cell 2||Row 2 - Cell 3
|-
|Row 3 - Cell 1||Row 3 - Cell 2||Row 3 - Cell 3
|}

This would render the following table

Header 1	Header 2	Header 3
Row 1 - Cell 1	Row 1 - Cell 2	Row 1 - Cell 3
Row 2 - Cell 1	Row 2 - Cell 2	Row 2 - Cell 3
Row 3 - Cell 1	Row 3 - Cell 2	Row 3 - Cell 3

You can also render the same table placing each cell on its own line in the editor. This is often necessary for tables with longer or more complicated text in a single cell. Note, only a single pipe is used to call out a new cell in this case.

{|
|Header 1||Header 2||Header 3
|-
|Row 1 - Cell 1
|Row 1 - Cell 2
|Row 1 - Cell 3
|-
|Row 2 - Cell 1
|Row 2 - Cell 2
|Row 2 - Cell 3
|-
|Row 3 - Cell 1
|Row 3 - Cell 2
|Row 3 - Cell 3
|}

And the same exact table is created, seen below.

Header 1	Header 2	Header 3
Row 1 - Cell 1	Row 1 - Cell 2	Row 1 - Cell 3
Row 2 - Cell 1	Row 2 - Cell 2	Row 2 - Cell 3
Row 3 - Cell 1	Row 3 - Cell 2	Row 3 - Cell 3

A great deal of styling and formatting can be done to tables. Refer to the MediaWiki's help page on tables here for more information.

Table Example: How To with Images

Use the "how-to-table" CSS class to style the two column tables we use in the "How To" sections of our articles. Declare the table class after the {| at the beginning of the table.

{|class="how-to-table"
|
row 1 column 1
|
row 1 column 2
|-
|
row 2 column 1
|
row 2 column 2
|}

This is a sample from the setup instructions taken from the Tabular Layout article.

Select the Data Column.
Select the Header Extractor property.
- Here you will set an extractor to locate the column header on the document for the selected Data Column.
Using the dropdown selector, select the Extractor Type you wish to configure to return the column header.
- You can use whatever Extractor Type you want to get the job done. You may select Reference to reference a Data Type or Value Reader extractor object you've configured already. Or, you can select one of the other Extractor Types to configure extraction locally.
- We're going to select List Match.

The List Match extractor is well suited for our purposes here. Ultimately, we will enter a list of various ways a "Quantity" column can be labeled.

For example, this document labels quantities of each item ordered as "HRS / QTY"
So, we've added HRS / QTY to the Local Entries list.
Other documents use the label "Quantity" or "Shipped". So, we've added Quantity and Shipped to the list as well.

You would then continue adding variations to the list until all variations of the "Quantity" column's header labels are extracted for every variation of the table.

Or more generally, until a result for the column header is extracted using whatever Extractor Type you've chosen to configure.

Table Example: Property Details

This is generally unused on more current wiki articles, but gives you a decent example of table styling.

{|cellpadding=10 cellspacing=5 style="margin:auto"
|-style="background-color:#36B0A7; color:white"
|style="width:17%"|'''Property'''
|style="width:17%"|'''Default Value'''
|'''Information'''
|-style="background-color:#36B0A7; color:white"
|colspan=3|General Properties
|-style="background-color:#ddf5f5 
|Property Name||Default Val||Info
|}

Property	Default Value	Information
General Properties
Property Name	Default Val	Info

Tabbed Containers

Tabbed containers can be very helpful for step by step "how to" instructions. Below is the markup for a simple tabbed container.

<tabs>
<tab name="Step 1">
Text for the first tab.
</tab>
<tab name="Step 2">
Text for the second tab.
</tab>
</tabs>

It produces the following result.

Step 1Step 2

Text for the first tab.

Text for the second tab.

Each container must start with the <tabs> tag and end with the </tabs>

Each tab must start with the <tab> tag and end with the </tab> tag.

Text inside each tab is formatted just as you would a full page.

Tabs may be named using the name modifier, using the following syntax <tab name="Tab Name">

Single Tab Containers

You may also find single tab containers useful. Instead of multiple clickable tabs, you will render a single container, which you can collapse by clicking the tab heading. The heading will read "Hide contents" unless otherwise styled.

<tab>
Tab text goes here
</tab>

Show contentsHide contents

Tab text goes here

You can also render the container collapsed, enabling the user to expand the text by clicking on the container. This is done with the "collapsed" tag.

<tab collapsed name="Click Me">
You clicked me!
</tab>

Click MeClick Me

You clicked me!

Information Boxes

FYI Boxes

{|cellpadding=10 cellspacing=5 style="margin:12px"
|-
|style="font-size:125%; background-color:#36b0a7; color:white; width:28px; text-align:center"|'''FYI'''
|style="border: 4px solid #36b0a7"|
Did you know something?  I'm explaining that to you here.
|}

FYI

Did you know something? I'm explaining that to you here.

Caution/Attention Boxes

{|cellpadding=10 cellspacing=5 style="margin:12px"
|-
|style="font-size:250%; background-color:#f89420; color:white; width:28px; text-align:center"|&#9888;
|style="border: 4px solid #f89420"|
Some of the tabs in this tutorial are longer than the others.  Please scroll to the bottom of each step's tab before going to the step.
|}

⚠	Some of the tabs in this tutorial are longer than the others. Please scroll to the bottom of each step's tab before going to the step.

Download Box

{|cellpadding="10" cellspacing="5" 
|-
|style="font-size:14pt; color:#f89420; border: 2px solid #f89420; width:40px"|[[File:Asset 22@4x.png]]
|style="border: 2px solid #f89420"|
You may download and import the files below into your own Grooper environment (version 2023).  The first contains a '''Project''' with several '''Content Models''' used as examples throughout this article.  The second contains some example '''Batches''' of sample documents.
* [[Media:2023_Projects_Wiki_-_CSS_Data_Viewer_Styling.zip]]
* [[Media:2023_Batches_Wiki_-_CSS_Data_Viewer_Styling.zip]]
|}

You may download and import the files below into your own Grooper environment (version 2023). The first contains a Project with several Content Models used as examples throughout this article. The second contains some example Batches of sample documents.

Work-In-Progress Box

{|cellpadding=10 cellspacing=5 style="margin:12px"
|-style="background-color:#ed2330; color:white"
|style="font-size:14pt"|'''WIP'''
|
This article is a work-in-progress or created as a placeholder for testing purposes.  This article is subject to change and/or expansion.  It may be incomplete, inaccurate, or stop abruptly.

This tag will be removed upon draft completion.
|}

WIP

This article is a work-in-progress or created as a placeholder for testing purposes. This article is subject to change and/or expansion. It may be incomplete, inaccurate, or stop abruptly.

This tag will be removed upon draft completion.

Ultra Important Box

{|cellpadding=10 cellspacing=5 style="margin:12px"
|-
|style="font-size:200%; background-color:#662d91; color:white; width:28px; text-align:center"|'''&#8252;'''
|style="border: 4px solid #662d91"|
It's purple and there's two exclamation marks.  Must be important.
|}

‼	It's purple and there's two exclamation marks. Must be important.