Writing Knowledge Base Articles

This guide will teach you the basics of markdown formatting that you can use when writing articles in the CMS for the W&W Knowledge Base.

Don’t worry - Markdown is much simpler than it looks!

What is Markdown?

Markdown is a simple way to add formatting to your text using plain characters. Instead of clicking buttons like in Microsoft Word, you type special characters that tell the system how to format your text.

For example, typing **bold text** will make the words bold text appear in bold.

You may recognise this as the same way that formatting is applied in WhatsApp, though our version has a lot more features!

Creating a new article

1. Log in to the CMS at https://wiki.wovenandwoods.com/admin
2. Navigate to the collection where you want to add the article (i.e. Business Development).
3. Click “New …” to create a new article (i.e. New Business Development).
4. Fill in the title and description fields at the top.
5. If you want to use any Starlight components, import them at the very top of your article (see the Steps component example below).
6. Start writing your article below the description field using the markdown formatting explained in this guide.
7. When you’re done, check the preview in the right hand pane to see how it looks.
8. If everything is correct, click the “Publish” button to make your article live.
9. Your article should appear on on the knowledge base site within a few minutes.

Basic text formatting

Making text bold or italic

To make text bold, surround it with two asterisks on each side:

**This text will be bold**

To make text italic, use one asterisk on each side:

*This text will be italic*

You can combine them for bold and italic:

***This text is both bold and italic***

Creating headings

Headings help organize your article into sections. Use the # symbol:

# Main Title (biggest heading)
## Section Heading
### Subsection Heading
#### Smaller Heading

Important: Your article title is automatically created from the title field in Decap CMS, so start your content with ## for your first section.

Adding links

To create a link, use square brackets for the text and parentheses for the web address:

[Click here to visit our website](https://yourwebsite.com)

For links to other pages in your knowledge base:

[See our Getting Started guide](../getting-started)

Adding images

To add an image, use an exclamation mark, followed by square brackets for the description, then parentheses for the image location:

![A screenshot of the login page](../images/login-screenshot.png)

Tip: In Decap CMS, you can usually upload images using the media library and insert them automatically.

Creating lists

Bullet point lists

For simple bullet points, use a dash (-) or asterisk (*):

- First item
- Second item
- Third item
  - You can indent for sub-items
  - Like this
- Back to main list

Numbered lists

For numbered lists, just use numbers:

1. First step
2. Second step
3. Third step
   1. Sub-step
   2. Another sub-step
4. Fourth step

Tip: The actual numbers don’t matter - markdown will renumber them automatically. You could write 1. 1. 1. and it would still display as 1. 2. 3.

Steps

When you’re writing instructions that describe a process people need to follow in order, use the Steps component instead of regular numbered lists. This makes it crystal clear what order things should be done in and looks more professional.

Here’s an example:

1. Open your web browser
2. Go to the login page
3. Enter your username and password
4. Click the “Sign In” button
5. You should now see your dashboard

First, add this import section at the very top of your article:

import { Steps } from '@astrojs/starlight/components';

Then use it like this:

<Steps>
1. Open your web browser
2. Go to the login page
3. Enter your username and password
4. Click the "Sign In" button
5. You should now see your dashboard
</Steps>

When to use Steps vs regular numbered lists:

• Use Steps for: Processes, tutorials, installation guides, troubleshooting steps
• Use regular numbered lists for: Rankings, priorities, simple lists that happen to have numbers

Adding code or technical terms

Inline code

For technical terms, file names, or short code snippets, surround text with backticks (`).

Remember that a backtick (`) is different from a regular quote (’) or double quote (”). On Windows, you’ll find in the top left corner of your keyboard, next to the number 1 key. On a Mac keyboard, it’s next to the number 1 key as well, but you may need to hold down the Shift key to type it.

`Click on the `Save` button to save your changes.
The file should be named `config.txt`.`

Code blocks

For longer code examples, use three backticks before and after:

```
function sayHello() {
    console.log("Hello world!");
}
```

Asides and special boxes

The knowledge base supports special highlighted boxes for important information. To use these boxes, you need to import the Aside component at the top of your article:

import { Aside } from '@astrojs/starlight/components';

Note

Note

This is important information that readers should know.

<Aside type="note">
This is important information that readers should know.
</Aside>

Caution

Caution

Be careful when following these steps.

<Aside type="caution">
Be careful when following these steps.
</Aside>

Tip

Tip

Here’s a helpful suggestion to make things easier.

<Aside type="tip">
Here's a helpful suggestion to make things easier.
</Aside>

Danger

Danger

This action could have serious consequences.

<Aside type="danger">
This action could have serious consequences.
</Aside>

Tables

You can create simple tables using pipes (|):

Feature	Description	Available
Search	Find articles quickly	Yes
Comments	Reader feedback	No
Export	Download as PDF	Yes

| Feature | Description | Available |
| --- | --- | --- |
| Search | Find articles quickly | Yes |
| Comments | Reader feedback | No |
| Export | Download as PDF | Yes |

Tip: Don’t worry about making the pipes line up perfectly - it will work either way.

Line breaks and paragraphs

• New paragraph: Leave a blank line between paragraphs

This is the first paragraph.

This is the second paragraph.

This is the first paragraph.

This is the second paragraph.

• Line break: End a line with two spaces, then press Enter

This is the first line.
This is the second line.

This is the first line.__
This is the second line.

(Replace __ with two actual spaces)

Starlight components

As mentioned earlier, you can expand Markdown using Starlight components. These are pre-built blocks of content that you can insert into your articles to add extra functionality or styling.

Adding them can be a bit tricky but - if you’d like to give it a go - you can find a list of available components and how to use them in the Starlight documentation.

Common mistakes to avoid

1. Forgetting spaces: There needs to be a space after # for headings and after - for lists
2. Not closing formatting: If you start with **bold you must end with **
3. Wrong quote marks: Use backticks (`) not regular quotes (”) for code
4. Missing blank lines: Always leave blank lines before and after headings, lists, and code blocks

Quick reference cheat sheet

What you want	What to type	Result
Bold text	**bold**	bold
Italic text	*italic*	italic
Heading	## Heading	Large heading text
Link	[text](url)	Clickable link
Image		Displays image
Bullet list	- item	• item
Code	`code`	code

Writing tips

1. Use clear headings to break up your content
2. Keep paragraphs short - 2-3 sentences is often enough
3. Use bullet points to make information easy to scan
4. Add images to show what you’re explaining
5. Test your links to make sure they work

Getting help

• Preview pane: Use the preview feature in Decap CMS to see how your article will look
• Switch to rich text mode: If you get stuck, you can always use the Rich Text editor in Decap. It doesn’t support as many features as Markdown, but it’ll do the job.