Creating Markdown pages for www.whi.org
A Markdown document is a text document with extra symbols added so it can be converted into a simple web page. (This page is created from a Markdown document).
Markdown is used for several types of pages on the WHI.org website.
- Stand alone web pages (e.g. Sigs, Working with WHI Data)
- News stories
- To make a page a news story, click the News story check box and select if you want it to appear on the main page and/or the ppt page news sections.
- Editable sections of programmer created pages. (e.g. the bottom section of the propose a paper WHI page)
- Ancillary study pages/subsites
- Usually markdown for ancillary study pages is done in the WHIST application, but if the study needs more complicated pages then https://devccc.whi.org/db/md-edit can be used to create those sites.
Editing and Publishing Markdown pages
Although Markdown can be written in any editor, to change www.whi.org markdown pages, you need to eventually put the markdown into our edit screen, https://devccc.whi.org/db/md-edit. This screen has a handy previewer and has a few extra WHI specific options.
Changes made in this screen are made to a test version of the page. You can see a preview the current changes in the edit screen or at http://www.whi.org/mdtest/yourpath. (There is a link at the top of the edit screen to this path). Once you are happy with your changes, click the publish button. This will "publish" those changes and they will be visible at http://www.whi.org/md/yourpath.
- Only the programmers can add something to the www.whi.org menu
- Currently only programmers can upload documents (pdfs, etc.) and/or images
Common Markdown
The editor we use has icons at the top for formating text, but here's a short list of the common symbols. I find it faster to type in the symbols myself.
This Markdown guide is a handy cheat sheet for Markdown syntax. Note some of the extended syntax options in this document do not work in our markdown pages.
| Element | Markdown Syntax | Example |
|---|---|---|
| Heading | # H1
| H1 |
| Bold | **bold text** | bold text |
| Italic | *italicized text* | italicized text |
| Link | [title](https://www.example.com) | title |
| Ordered List |
1. First item | |
| Unordered List |
- First item
| |
| Horizontal Line | --- | |
| Image |  | |
| Code | `code` | code |
| Tables |
| col1 | col2 | | |
| Footnotes | Here's a sentence with a reference to a footnote. [^1] [^1]: the footnote text. |
Common Markdown issues
- Some markdown symbols need to be the first character of the line (e.g. # headings). any spaces or indentation before them will make them not work.
- Creating new lines - to force a line break, add a blank line between the two items or add two spaces to the end of the first line.
Extending Markdown
You can include html code in Markdown documents. I don't expect we'll do much of that in these pages, but there are a few tricks that are handy to know about.
One is surrounding some markdown with a <div class="xxx"> at the start and a <\div> tag at the end to create a section or division. The class or classes you assign to the div will "turn on" special formatting/layout. Note that you need to have a blank line after a <div> before the markdown starts. This is needed to make the markdown work.
Creating multiple column layouts
Below is an example of a two column layout. The Working with WHI Data page uses this technique. You can have up to 12 columns in a single row.
WHI Data Dictionaries
Annually WHI creates and releases a cumulative dataset for analysis. While the data files are only available to investigators with approved paper proposals, the corresponding data dictionaries provide a directory of the available variables, including their distributions within the study population.
Annual Progress Reports
Progress reports are annual summaries of the cumulative data at a specific point in time. They may be the easiest way to locate quick counts in the WHI data.
To do this first you create a row with a div using the row class. Then you create up to 12 columns in that row with divs that use the col class. Your markdown goes between the col div start and end tags.
e.g copy this into your markdown to do a 2 column layout.
<div class="row">
<div class="col">
Markdown for col 1
</div>
<div class="col">
Markdown for col 2
</div>
</div>
If you want more than 2 columns, just add more column sections (up to 12)
<div class="col">
Markdown for col 1
</div>
Look here for more advanced column layout options
Using the "green-box" class
Annual Progress Reports
Progress reports are annual summaries of the cumulative data at a specific point in time. They may be the easiest way to locate quick counts in the WHI data.
<div class="green-box">
### Annual Progress Reports
[Progress reports](https://www.whi.org/page/progress-reports) are annual summaries of the
cumulative data at a specific point in time. They may be the easiest way to locate quick
counts in the WHI data.
</div>
Note that there has to be a blank line after the div and the markdown
use break tags <br /> for extra spacing between lines
text
more text
text
<br />
<br />
more text
Indenting, Margins and Padding
A more flexible way of creating extra space around something is to use the margin and/or padding classes. There are several of these classes, the names follow these rules.
- m or p for margin or padding
- An optional second letter if you only want the margin or padding applied to some areas of the box. s,e,t or b for start, end, top or bottom (also x for left and right or y for top and bottom), or no second letter if you want
- a dash and a number 1-5 for the amount of padding/margin
e.g. "m-3" puts a medium amount of padding all around something.
"ms-3" would only add margin to the start (left side) of something
Examples (I also added borders so you can see what's going on.
