In a Nutshell

  • You will use WebMatrix software to download your website, preview it in the web browser and to publish the changes.
  • You will use MarkdownPad 2 to edit the content of the site because it is designed for editing the kind of files that make this website work. You can use WebMatrix to do all the editing, but MarkdownPad is more pleasant.
  • Only make changes to files that are in the user\pages folder or the user\config\site.yaml file
  • Text that you see on the footer of the site is edited in the user\config\site.yaml file.
  • You will clear the cache after every change to the content. There will be a delay loading the site after the cache is cleared.
  • When writing text in Front-matter, you must be very careful with formatting. You cannot use quotes and putting a space in the wrong place can result in the site going down.
  • If you make an error in the Front-matter, you will get an error telling you what you did.
  • Make only small changes in Front-matter and clear the cache to see how it looks.
  • Writing in Markdown is actually very easy and pleasant compared to what you used in the past but it might look tough at first.
  • You can put HTML code in your Markdown text and in your Front-matter but let me help you if you are not getting the desired result.

Some HTML that you may want sprinkle in occasionally into your content.

<br /> - this is a line feed, you may need it in Markdown or Front-matter.
<p></p> - this is a paragraph tag you may need it in Front-matter.

That is a pretty short list, pretty much everything else you want to do can be done with Markdown Pad tools.

  • Don't let the lack of online editing make you feel this CMS is inferior. It is a new way of doing things and there are significant advantages to using it over older systems. There will be an online editor plugin for this system some day in the not too distant future.

Download Software

You will need some software for this one

Your old site used DotNetNuke which is vastly different than what we are using now. This new CMS is called Grav http://getgrav.org. Currently Grav does not have an online editor like you had with the old site so you are going to need some software. At some point in the future, there will be an online editor available which should allow you to make updates without using the software I am having you install.

Because you are a Windows user, I am going to set you up with two programs. Microsoft WebMatrix is a free web developers tool that you will use to run your website on your computer so you can see the changes you make. Once changes are made, all you do is press the Publish button to make your changes live. The other program is optional, it is called Markdown Pad 2 and it just helps you to write content.

I could also set Grav up so that you could do your edits online using a third party website called GitHub or BitBucket, but for now because you are the only editor and you use Windows, these tools will work great.

Download Microsoft WebMatrix

Download Microsoft WebMatrix

WebMatrix is a free web development tool from Microsoft. The website is hosted on Microsoft Azure and Web Matrix allows you to run the site on your computer so that you can see what the site looks like before you publish. Publishing your changes is a simple push of the publish button.

Download WebMatrix from here.

Once you download it, install the software onto your computer.

Create a site in WebMatrix

Note: this step is a one time setup:

  1. Open Windows Explorer (not Internet Explorer) and create a folder called something like KS Foundation Website. Create this folder in your My Documents folder.
    Sample Image
  2. Launch WebMatrix and Open a Folder as Site as shown in the picture below.
    Sample Image
  3. Browse to the folder that you created in the first step and choose Open
  4. Once the site is created you need to configure it to run with PHP 5.5. To do this you need to choose Site from the bottom-left side and then Settings from the top-left side. Click on the image below for a better picture.
    Sample Image

Download a copy of your website and make sure it works.

In order to gain access to the website for editing, I have emailed you a Publish Profile file that you need to save to your computer. You will only need this file once.

  1. On the Ribbon Bar for WebMatrix, press on the Remote tab and choose Settingsas shown in the picture below
    Sample Image
  2. From the dialog that opens, choose import Publish Profileand browse to the publish profile file that I emailed to you and open it
    Sample Image
  3. Once your Publish Profile has been imported, you can start to work on your website. The first thing you need to do is to press the download button.
    Sample Image
  4. Once your site has finished downloading, return to the Home tab and and press the Run button. Your site will launch in a web browser and it should work perfectly.

MarkdownPad 2

MarkdownPad 2

MarkdownPad is an easy-to-use Markdown Editor for Windows. There is a free version that should meet all your needs. If you do use MarkdownPad a lot, you should purchase it as the price is very reasonable.

Download MarkdownPad 2

Once you have it downloaded, install the software and configure it so that it is the default editor for .md files.

To set MarkdownPad as your default Markdown editor,

  1. browse to the folder where the files that make up your site are. This is probably documents\KS Foundation Site, it is the folder you created when setting up WebMatrix.
  2. you will see a folder called user, open that page and go to the pages folder. In there you will find the 01.home folder which contains most of the content for your site.
  3. Once in the 01.home folder, right-click on the file called modular.mdand choose Open With from the menu that comes up. You will then choose MarkdownPad to open that file. MarkdownPad will now be the default editor for .md files.
  4. With MarkdownPad open go to TOOLS>OPTIONS and in the Markdown tab tell it to ignore YAML Front-matter see image below.
    Sample Image

In the next section, you will learn what Markdown is and how to edit the content for your site.

Editing your content with Markdown and YAML Front-matter

The Kelly Shires Breast Cancer Foundation Website uses a Content Management System called Grav. Unlike most Content Management Systems, Grav does not need a database to work, all the content for the site is kept in plain text files with the extension .md. MD stands for MarkDown. Markdown is a simplified way of writing content for the Internet. You can write in plain text without a lot of toolbars and buttons to get you into trouble.

The reason your old site become so cluttered looking is because you are presented with too many options and the online editors do a poor job of creating the HTML that would make the site look and perform properly.

Structured content

With this new site, I (as the developer) have implemented all the design decisions leaving you (the content editor) with very little room to make poor design choices. You will find it very hard to make large bold pink lettering in Comic Sans font. With this site most of the content is in place and I don't expect you to be adding new sections but you need to learn where the structured content is and how to edit it.

Grav File Structure

Check out the image below to see where your files are located.
File Structure

The only place you need to familiarize yourself with is the user\pages\01.home folder. Inside that folder you will find a series of folders that start with an underscore character. _showcase, _donate, _shop etc. Each of these folders contains an .md file. These .md files contain two things: Structured data and written text using Markdown which sometimes needs bit of html code.

You will find different file names for the .md files. For the _showcase folder you will find showcase.md. The name of the file tells the CMS what template to use. In this example, the showcase template contains all the complicated code that makes the showcase function. The showcase is the large slide show at the top of the site.

The top of your .md file contains structured data called Front-matter. It is easy to make mistakes in here so be careful. Front-matter starts after the first three dashes --- and ends after the second set of three dashes ---.

---
title: Name of this section
menu: What will show in the menu
class: title-section
uniqueid: ass
bgclass: whitebg
---

The example shown above is the front matter of a simple page. The only thing you may want to change there is the title.

---
title: Showcase
menu: Home
class: title-section text-center
slides:
  - image: banner1.jpg
    heading: "Helping Breast Cancer Survivors since 2002"
    subheading: "And having a good time doing so."
  - image: banner2.jpg
    heading: "Ladies - please join us at our next event"
    subheading: "Snowmobile rides, four wheeler rides, golf tournaments"
  - image: banner3.jpg
    heading: "Assistance is available"
    subheading: "We provide assistance to women to help with the expenses of having breast cancer"
  - image: banner4.jpg
    heading: "Assistance is available"
    subheading: "We provide assistance to women to help with the expenses of having breast cancer"    
highlight:
  - header: Get assistance
    text: "The Snow Run for Fun Trust was established to help women who have been recently diagnosed with Breast Cancer. There are many unforseen expenses you may face, and which your health insurance program may not cover."
    icon: life-saver
    url: assistance
  - header: Make a donation
    text: "We rely on your generousity to help make the lives of breast cancer patients less challenging."
    icon: money
    url: donate
  - header: Fundraising events
    text: "The Snow Run was formed out of a passion for snowmobiling, and an equal passion for helping women who truly needed help in a time of need."
    icon: heart-o
    url: events
  - header: Merchandise
    text: "Shop for the cause... Support breast cancer survivors by purchasing items that we have had designed especially for our foundation."
    icon: shopping-cart
    url: shop 

---

# Offering financial assistance to breast cancer patients 
<span></span>

What you are seeing above is the contents of the actual showcase.md file. As you see, all the content that makes the top of the website work is contained in Front-matter. I know the words in there are not correct, so this is all you need to edit to fix it up. But BE CAREFUL if you put a space in the wrong place, the site will go down. Always test your changes before hitting the publish button.

What is Markdown?

Markdown is plain text that gets parsed by the CMS and converted into HTML. HTML is what is used to display content on a web page. Everything below the second ---three dashes is where your Markdown will go.

So take what we have so far on this page:

---
title: What is Markdown?

---
**Markdown** is plain text that gets parsed by the CMS and converted into HTML.  HTML is what is used to display content on a web page. Everything below the second `---`three dashes is where your Markdown will go.

So take what we have so far on this page:

Above is what is making this page up until this point. Below is a full description of what it is and why we use it.

Let's face it: Writing content for the Web is tiresome. WYSIWYG editors help alleviate this task, but they generally result in horrible code, or worse yet, ugly web pages.

Markdown is a better way to write HTML, without all the complexities and ugliness that usually accompanies it.

Some of the key benefits are:

  1. Markdown is simple to learn, with minimal extra characters so it's also quicker to write content.
  2. Less chance of errors when writing in markdown.
  3. Produces valid XHTML output.
  4. Keeps the content and the visual display separate, so you cannot mess up the look of your site.
  5. Write in any text editor or Markdown application you like.
  6. Markdown is a joy to use!

John Gruber, the author of Markdown, puts it like this:

The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. While Markdown’s syntax has been influenced by several existing text-to-HTML filters, the single biggest source of inspiration for Markdown’s syntax is the format of plain text email. -- John Gruber

Without further delay, let us go over the main elements of Markdown and what the resulting HTML looks like:

Headings

Headings from h1 through h6 are constructed with a # for each level:

# h1 Heading
## h2 Heading
### h3 Heading
#### h4 Heading
##### h5 Heading
###### h6 Heading

Renders to:

h1 Heading

h2 Heading

h3 Heading

h4 Heading

h5 Heading
h6 Heading

HTML:

<h1>h1 Heading</h1>
<h2>h2 Heading</h2>
<h3>h3 Heading</h3>
<h4>h4 Heading</h4>
<h5>h5 Heading</h5>
<h6>h6 Heading</h6>



Horizontal Rules

The HTML <hr> element is for creating a "thematic break" between paragraph-level elements. In markdown, you can create a <hr> with any of the following:

  • ___: three consecutive underscores
  • ---: three consecutive dashes
  • ***: three consecutive asterisks

renders to:






Body Copy

Body copy written as normal, plain text will be wrapped with <p></p> tags in the rendered HTML.

So this body copy:

Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.

renders to this HTML:

<p>Lorem ipsum dolor sit amet, graecis denique ei vel, at duo primis mandamus. Et legere ocurreret pri, animal tacimates complectitur ad cum. Cu eum inermis inimicus efficiendi. Labore officiis his ex, soluta officiis concludaturque ei qui, vide sensibus vim ad.</p>



Emphasis

Bold

For emphasizing a snippet of text with a heavier font-weight.

The following snippet of text is rendered as bold text.

**rendered as bold text**

renders to:

rendered as bold text

and this HTML

<strong>rendered as bold text</strong>

Italics

For emphasizing a snippet of text with italics.

The following snippet of text is rendered as italicized text.

_rendered as italicized text_

renders to:

rendered as italicized text

and this HTML:

<em>rendered as italicized text</em>

strikethrough

In GFM (GitHub flavored Markdown) you can do strikethroughs.

~~Strike through this text.~~

Which renders to:

Strike through this text.

HTML:

<del>Strike through this text.</del>



Blockquotes

For quoting blocks of content from another source within your document.

Add > before any text you want to quote.

> **Fusion Drive** combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.

Renders to:

Fusion Drive combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.

and this HTML:

<blockquote>
  <p><strong>Fusion Drive</strong> combines a hard drive with a flash storage (solid-state drive) and presents it as a single logical volume with the space of both drives combined.</p>
</blockquote>

Blockquotes can also be nested:

> Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue.
Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.
>> Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor
odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.

Renders to:

Donec massa lacus, ultricies a ullamcorper in, fermentum sed augue. Nunc augue augue, aliquam non hendrerit ac, commodo vel nisi.

Sed adipiscing elit vitae augue consectetur a gravida nunc vehicula. Donec auctor odio non est accumsan facilisis. Aliquam id turpis in dolor tincidunt mollis ac eu diam.



Lists

Unordered

A list of items in which the order of the items does not explicitly matter.

You may use any of the following symbols to denote bullets for each list item:

* valid bullet
- valid bullet
+ valid bullet

For example

+ Lorem ipsum dolor sit amet
+ Consectetur adipiscing elit
+ Integer molestie lorem at massa
+ Facilisis in pretium nisl aliquet
+ Nulla volutpat aliquam velit
  - Phasellus iaculis neque
  - Purus sodales ultricies
  - Vestibulum laoreet porttitor sem
  - Ac tristique libero volutpat at
+ Faucibus porta lacus fringilla vel
+ Aenean sit amet erat nunc
+ Eget porttitor lorem

Renders to:

  • Lorem ipsum dolor sit amet
  • Consectetur adipiscing elit
  • Integer molestie lorem at massa
  • Facilisis in pretium nisl aliquet
  • Nulla volutpat aliquam velit
    • Phasellus iaculis neque
    • Purus sodales ultricies
    • Vestibulum laoreet porttitor sem
    • Ac tristique libero volutpat at
  • Faucibus porta lacus fringilla vel
  • Aenean sit amet erat nunc
  • Eget porttitor lorem

And this HTML

<ul>
  <li>Lorem ipsum dolor sit amet</li>
  <li>Consectetur adipiscing elit</li>
  <li>Integer molestie lorem at massa</li>
  <li>Facilisis in pretium nisl aliquet</li>
  <li>Nulla volutpat aliquam velit
    <ul>
      <li>Phasellus iaculis neque</li>
      <li>Purus sodales ultricies</li>
      <li>Vestibulum laoreet porttitor sem</li>
      <li>Ac tristique libero volutpat at</li>
    </ul>
  </li>
  <li>Faucibus porta lacus fringilla vel</li>
  <li>Aenean sit amet erat nunc</li>
  <li>Eget porttitor lorem</li>
</ul>

Ordered

A list of items in which the order of items does explicitly matter.

1. Lorem ipsum dolor sit amet
2. Consectetur adipiscing elit
3. Integer molestie lorem at massa
4. Facilisis in pretium nisl aliquet
5. Nulla volutpat aliquam velit
6. Faucibus porta lacus fringilla vel
7. Aenean sit amet erat nunc
8. Eget porttitor lorem

Renders to:

  1. Lorem ipsum dolor sit amet
  2. Consectetur adipiscing elit
  3. Integer molestie lorem at massa
  4. Facilisis in pretium nisl aliquet
  5. Nulla volutpat aliquam velit
  6. Faucibus porta lacus fringilla vel
  7. Aenean sit amet erat nunc
  8. Eget porttitor lorem

And this HTML:

<ol>
  <li>Lorem ipsum dolor sit amet</li>
  <li>Consectetur adipiscing elit</li>
  <li>Integer molestie lorem at massa</li>
  <li>Facilisis in pretium nisl aliquet</li>
  <li>Nulla volutpat aliquam velit</li>
  <li>Faucibus porta lacus fringilla vel</li>
  <li>Aenean sit amet erat nunc</li>
  <li>Eget porttitor lorem</li>
</ol>

TIP: If you just use 1. for each number, Markdown will automatically number each item. For example:

1. Lorem ipsum dolor sit amet
1. Consectetur adipiscing elit
1. Integer molestie lorem at massa
1. Facilisis in pretium nisl aliquet
1. Nulla volutpat aliquam velit
1. Faucibus porta lacus fringilla vel
1. Aenean sit amet erat nunc
1. Eget porttitor lorem

Renders to:

  1. Lorem ipsum dolor sit amet
  2. Consectetur adipiscing elit
  3. Integer molestie lorem at massa
  4. Facilisis in pretium nisl aliquet
  5. Nulla volutpat aliquam velit
  6. Faucibus porta lacus fringilla vel
  7. Aenean sit amet erat nunc
  8. Eget porttitor lorem



Code

Inline code

Wrap inline snippets of code with `.

In this example, `<section></section>` should be wrapped as **code**.

Renders to:

In this example, <section></section> should be wrapped with code.

HTML:

<p>In this example, <code>&lt;section&gt;&lt;/section&gt;</code> should be wrapped with <strong>code</strong>.</p>

Indented code

Or indent several lines of code by at least four spaces, as in:

  // Some comments
  line 1 of code
  line 2 of code
  line 3 of code

Renders to:

// Some comments
line 1 of code
line 2 of code
line 3 of code

HTML:

<pre>
  <code>
    // Some comments
    line 1 of code
    line 2 of code
    line 3 of code
  </code>
</pre>

Block code "fences"

Use "fences" ``` to block in multiple lines of code.

``` markup
Sample text here...
```
Sample text here...

HTML:

<pre>
  <code>Sample text here...</code>
</pre>



Tables

Tables are created by adding pipes as dividers between each cell, and by adding a line of dashes (also separated by bars) beneath the header. Note that the pipes do not need to be vertically aligned.

| Option | Description |
| ------ | ----------- |
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext    | extension to be used for dest files. |

Renders to:

Option Description
data path to data files to supply the data that will be passed into templates.
engine engine to be used for processing templates. Handlebars is the default.
ext extension to be used for dest files.

And this HTML:

<table>
  <tr>
    <th>Option</th>
    <th>Description</th>
  </tr>
  <tr>
    <td>data</td>
    <td>path to data files to supply the data that will be passed into templates.</td>
  </tr>
  <tr>
    <td>engine</td>
    <td>engine to be used for processing templates. Handlebars is the default.</td>
  </tr>
  <tr>
    <td>ext</td>
    <td>extension to be used for dest files.</td>
  </tr>
</table>

Right aligned text

Adding a colon on the right side of the dashes below any heading will right align text for that column.

| Option | Description |
| ------:| -----------:|
| data   | path to data files to supply the data that will be passed into templates. |
| engine | engine to be used for processing templates. Handlebars is the default. |
| ext    | extension to be used for dest files. |
Option Description
data path to data files to supply the data that will be passed into templates.
engine engine to be used for processing templates. Handlebars is the default.
ext extension to be used for dest files.




Links

Basic link

[Assemble](http://assemble.io)

Renders to (hover over the link, there is no tooltip):

Assemble

HTML:

<a href="http://assemble.io">Assemble</a>

Add a title

[Upstage](https://github.com/upstage/ "Visit Upstage!")

Renders to (hover over the link, there should be a tooltip):

Upstage

HTML:

<a href="https://github.com/upstage/" title="Visit Upstage!">Upstage</a>

Named Anchors

Named anchors enable you to jump to the specified anchor point on the same page. For example, each of these chapters:

# Table of Contents
  * [Chapter 1](#chapter-1)
  * [Chapter 2](#chapter-2)
  * [Chapter 3](#chapter-3)

will jump to these sections:

## Chapter 1 <a id="chapter-1"></a>
Content for chapter one.

## Chapter 2 <a id="chapter-2"></a>
Content for chapter one.

## Chapter 3 <a id="chapter-3"></a>
Content for chapter one.

NOTE that specific placement of the anchor tag seems to be arbitrary. They are placed inline here since it seems to be unobtrusive, and it works.




Images

Images have a similar syntax to links but include a preceding exclamation point.

![Minion](http://octodex.github.com/images/minion.png)

Minion

or

![Alt text](http://octodex.github.com/images/stormtroopocat.jpg "The Stormtroopocat")

Alt text

Like links, Images also have a footnote style syntax

![Alt text][id]

Alt text

With a reference later in the document defining the URL location:

[id]: http://octodex.github.com/images/dojocat.jpg  "The Dojocat"

Clear the cache

With your local setup of the website, you may find that when you make changes, they do not show up. This is because Grav builds and caches the site so that it is very fast to load for visitors. In a normal setup, any changes you make will trigger the Grav to recompile, but running it with WebMatrix this does not seem to happen so you need to clear your cache after every change in order to see the results.

Note: After you clear your cache, reload your offline site to see the changes, there will be a big delay loading the page which will let you know that it is cleared.

Note: You cannot use this link to clear the cache on the actual production website, it will only work from your local site.

FYI: With this CMS, all images are optimized which is one of the reasons the cache needs to be cleared. If you put an image on the site, you don't have to resize it first, Grav will do it for you - your site will load fast for most everybody.