Skip to content

Commit

Permalink
Turn the contribute pages into Markdown
Browse files Browse the repository at this point in the history 
Converted the pages in the contribute section into Markdown, closing okfn#31.
  • Loading branch information
@jgkim
jgkim committed Aug 13, 2015
1 parent 03b64aa commit 1433559
Show file tree
Hide file tree
Showing 8 changed files with 211 additions and 227 deletions.
59 changes: 28 additions & 31 deletions contribute/add-resource.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,46 +6,43 @@ authors:
lang: en
---

<p>Our resource library is a curated collection open data reosurces from across the community. Everyone can add a resource to the library. This is how to do so.</p>
<p class="lead">Our resource library is a curated collection of open data reosurces across the community. Everyone can add a resource to the library. This is how to do so.</p>

<h2>1. Add a folder</h2>
## 1. Add a folder

<p>Log in to github and head to the following <a href=https://github.com https://github.com/{{ site.github_username }}/tree/gh-pages/resources> link: </a></p>
Log in to GitHub and head to this [link](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/gh-pages/resources).

Every resource has a slug number. To add your resource, you need to give it a number. Look at the list and give you resource the number that follows the current last number in the list (e.g - if the number is 056, your resource should be named 057).
Click on the + sign in the directory line and add the number and a “/”. For example: 060/.
Every resource has a slug number. To add your resource, you need to give it a number. Look at the list and give your resource the number that follows the current last number in the list (e.g. if the number is 056, your resource should be named 057).

<h2>2. Add an index file</h2>
Click on the plus symbol <code class="icon-plus"><span>[plus icon]</span></code> in the directory line and add the number and a slash ('/'). For example: `060/`.

<p>Click on the + sign again. Add a file named index.md to your new folder.</p>
## 2. Add an index file

<h2>3. Add the resource</h2>
Click on the plus symbol <code class="icon-plus"><span>[plus icon]</span></code> again. Add a file named 'index.md' to your new folder.

<p>In the text editor, add the front matter fields in this pattern:</p>
<pre>
---
section: resources
lang: //Two first letters of the language, according to language code in this table.//
Author: //The name(s) of the person(s) who wrote the text//
Country: //One or more country by full name separated with a comma: “,”. If there is no specific country, write ‘global’//
Description: //1-5 lines that summarizes the text. //
Keywords: //Important descriptors of the text, separated with a comma, “,”.//
Link: //The link to the resource online//
MediaType: // List one out of these four types: Presentation, Article, / Publication, Video//
Notes: //Any notes or comments.//'
Publishing_date: //The year the resource was published, e.g. 2015.//
Publishing_entity: //The organisation(s) which publish the resource//
Region: North America,Latin America,Asia,Europe,Africa,Mena,Global
Title: //The name of the resource//
Topic: //Choose one out of these nine : The Basics,Advocacy,Privacy,civic engagement,Right for information,Data training,PolicyStandards.
---
</pre>
## 3. Add the resource

<h2>4. Make a pull request</h2>
In the text editor, add the front matter fields in this pattern:

<p>Click on “Create a new branch for this commit and start a pull request.” This will allow us to review your changes.</p>
---
section: resources
lang: Two first letters of the language, according to language code in this table
Author: The name(s) of the person(s) who wrote the text
Country: One or more countries by full name, separated with a comma: ",". If there is no specific country, write 'global'
Description: 1-5 lines that summarizes the text
Keywords: Important descriptors of the text, separated with a comma, ","
Link: The link to the resource online
MediaType: List one out of these four types: Presentation, Article, Publication, Video
Notes: Any notes or comments
Publishing_date: The year the resource was published, e.g. 2015
Publishing_entity: The organisation(s) which publish the resource
Region: North America, Latin America, Asia, Europe, Africa, Mena, Global
Title: The name of the resource
Topic: Choose one out of these nine: The Basics, Advocacy, Privacy, Civic Engagement, Right for Information, Data Training, Policy Standards
---

Thank you! All done!
## 4. Make a pull request

Click on “Create a new branch for this commit and start a pull request.” This will allow us to review your changes.

Thank you! All done!
54 changes: 27 additions & 27 deletions contribute/adding-terms.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,43 +5,43 @@ title: Adding a term to the glossary
authors:
- Mor Rubinstein
---
<p>Each glossary (meaning, each translated instance of the glossary), has three components:
<ul>
<li> A layout template for the glossary homepage: 'glossary.html'</li>
<li> A layout template for the glossary in each language: 'glossary/{lang}/index.md'</li>
<li> A directory of the glossary terms. Each term in the directory is listed as the url slug (In English, all lower case letters, and hyphens instead of white spaces).</li>
</ul>

<p></p>Currently, the English glossary has been updated and organized. Other languages please follow these <a href=http://new.opendatahandbook.org/contribute/translate-glossary/>instructions</a>
To add a new term, all you need is to have a Github account.</p>
<p class="lead">Each glossary (meaning, each translated instance of the glossary), has three components:</p>

<h3>1: Create a folder for the term</h3>
* A layout template for the glossary homepage: 'glossary.html'
* A layout template for the glossary in each language: 'glossary/{lang}/index.md'
* A directory of the glossary terms. Each term in the directory is listed as the url slug (In English, all lower case letters, and hyphens instead of white spaces).

<p>Log - in to Github and go to this <a href="https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/gh-pages/glossary/en/terms">link</a></p>
Currently, the English glossary has been updated and organized. Other languages please follow these [instructions](http://opendatahandbook.org/contribute/translate-glossary/).

<p>You will see a the branch name (“gh-pages”) and a directory. You will also see the breadcrumb <code>{{ site.github_repo }} / glossary / en / terms / + </code>. Click on the "+" to create a new folder.<p/>
To add a new term, all you need is to have a GitHub account.

<p> Write the name of the term that you want to add in a new slug (In English, all lower case letters, and hyphens instead of white spaces) and add a “/” at the end of the terms name. This will create a new folder name. </p>
## 1. Create a folder for the term

<h3>2: Create a file for your term</h3>
Log in to GitHub and go to this [link](https://github.com/{{ site.github_username }}/{{ site.github_repo }}/tree/gh-pages/glossary/en/terms)

<p> Now you will see the breadcrumb - <code>{{ site.github_repo }} / glossary / en / terms / your-new-term / + </code> Click on the “+” sign again. Now write in the path “index.md”. This will save the whole file as a markdown file. </p>
You will see the branch name ('gh-pages') and a directory. You will also see the breadcrumb `{{ site.github_repo }} / glossary / en / terms / +`. Click on the plus symbol <code class="icon-plus"><span>[plus icon]</span></code> to create a new folder.

<h3>3: Write the term definition </h3>
<p> In the text editor below, add the front matter (Jekyll way to mark the page) - </p>
<pre>
---
section: terms
lang: en
title: // the term name //
---
</pre>
Write the name of the term that you want to add in a new slug (In English, all lower case letters, and hyphens instead of white spaces) and add a slash ('/') at the end of the terms name. This will create a new folder name.

Write the term definition after the front matter as usual.
## 2. Create a file for your term

Now you will see the breadcrumb - `{{ site.github_repo }} / glossary / en / terms / your-new-term / + ` Click on the plus symbol <code class="icon-plus"><span>[plus icon]</span></code> again. Now write in the path 'index.md'. This will save the whole file as a markdown file.

## 3. Write the term definition

In the text editor below, add the front matter (Jekyll way to mark the page):

---
section: terms
lang: en
title: The term name
---

Write the term definition after the front matter as usual.

<h3>4: Make a pull request</h3>
## 4. Make a pull request

<p> Click on “Create a new branch for this commit and start a pull request.” This will allow us to review your changes. <p/>
Click on “Create a new branch for this commit and start a pull request.” This will allow us to review your changes.

<p>Thank you! All done! If the handbook editors are happy with your term, it will be added to the glossary. </p>
Thank you! All done! If the handbook editors are happy with your term, it will be added to the glossary.
81 changes: 36 additions & 45 deletions contribute/adding.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,74 +6,66 @@ authors:
- Sam Smith
---

<p class="lead">Most of what you need to know to add a new page is covered under ‘<a href="{{ "/contribute/editing/" | prepend: site.baseurl }}">Editing a page</a>’, so make sure you have first read through that section.</p>
<p class="lead">Most of what you need to know to add a new page is covered under '<a href="{{ "/contribute/editing/" | prepend: site.baseurl }}" rel="external">Editing a page</a>', so make sure you have first read through that section.</p>

<p>Adding a page follows a similar process to editing. Instead of locating your page, your first step is to locate your new page’s parent directory.</p>
Adding a page follows a similar process to editing. Instead of locating your page, your first step is to locate your new page's parent directory.

<h2>1: Create the page</h2>
## 1. Create the page

<p>First locate the parent directory, or folder, in which your file will live. If you are adding a page to the English language Handbook, for example, you should be in the '<strong>en</strong>' directory, where you’ll see a list of all the Handbook pages.</p>
First locate the parent directory, or folder, in which your file will live. If you are adding a page to the English language Handbook, for example, you should be in the '**en**' directory, where you'll see a list of all the Handbook pages.

<p>Above the list of pages is a breadcrumb trail <code>{{ site.github_repo }} / guide / en /</code>, to the right of which is a plus symbol <code><strong>+</strong></code>. Click the plus symbol to create your new page.</p>
Above the list of pages is a breadcrumb trail `{{ site.github_repo }} / guide / en /`, to the right of which is a plus symbol <code class="icon-plus"><span>[plus icon]</span></code>. Click the plus symbol to create your new page.

<h2>2: Name your file</h2>
## 2. Name your file

<p>You should now have a new file editor page open. The first editable section you are presented with is the ‘<em>Name your file</em>’ field. As we touched upon when looking at <a href="{{ "/contribute/editing/" | prepend: site.baseurl }}">editing files</a>, the file name corresponds to the URL of the page on the site. There are a few of rules to follow here:</p>
You should now have a new file editor page open. The first editable section you are presented with is the '*Name your file*' field. As we touched upon when looking at [editing files]({{ "/contribute/editing/" | prepend: site.baseurl }}), the file name corresponds to the URL of the page on the site. There are a few of rules to follow here:

<ul>
<li>The file name should reflect the title of the new page</li>
<li>Must be unique</li>
<li>Should be all lowercase</li>
<li>Words should be separated by hyphens (-)</li>
<li>File name should end with the extension '<em>.md</em>' (the .md extension indicates a markdown file)</li>
</ul>
* The file name should reflect the title of the new page
* Must be unique
* Should be all lowercase
* Words should be separated by hyphens (-)
* File name should end with the extension '*.md*' (the .md extension indicates a markdown file)

<p>As an example, if you were creating a page titled '<em>My Cool Page</em>', you would use a file name of:</p>
As an example, if you were creating a page titled '*My Cool Page*', you would use a file name of:

<pre>
<code>my-cool-page.md</code>
</pre>
my-cool-page.md

<p>Assuming you are creating this in the '<em>en</em>' directory, this would result in a URL of <em>{{ site.url }}/en/my-cool-page</em></p>
Assuming you are creating this in the '*en*' directory, this would result in a URL of *{{ site.url }}/en/my-cool-page*

<div class="note">
<h6>Note</h6>
<p>The actual words used in your file name are not crucial. It’s fine to use a more succinct version of your page title, for example.</p>
</div>

<h2>3: Formatting your content</h2>
## 3. Formatting your content

<p>This step is the same as when editing a page. You need to start your file with the Front Matter, then add your content, formatting it using Markdown. Here is a template to get you started:</p>
This step is the same as when editing a page. You need to start your file with the Front Matter, then add your content, formatting it using Markdown. Here is a template to get you started:

<pre>
<code>---
title: My Cool Page
authors:
- Fred Bloggs
---

##A large introductory paragraph.
---
title: My Cool Page
authors:
- Fred Bloggs
---

Regular paragraphs, separated by empty lines.
##A large introductory paragraph.

###A heading
Regular paragraphs, separated by empty lines.

Another paragraph.
###A heading

* Maybe
* a
* list</code>
</pre>
Another paragraph.

<p>When you’re done, click ‘<em>Propose new file</em>’.</p>
* Maybe
* a
* list

<h2>4: Make a pull request</h2>
When you’re done, click '*Propose new file*'.

<p>Once you have created your page(s) and updated the contents document, you're ready to make your pull request. Click the pull request icon to the right of the screen <code class="icon-git-pull-request"><span>[git pull-request icon]</span></code>, then click ‘<em>New pull request</em>’.</p>
## 4. Make a pull request

<p>At the top of the resulting comparison screen, you’ll see a row of select boxes. You want to make sure these are configured like so:</p>
Once you have created your page(s) and updated the contents document, you're ready to make your pull request. Click the pull request icon to the right of the screen <code class="icon-git-pull-request"><span>[git pull-request icon]</span></code>, then click '*New pull request*'.

</article>
At the top of the resulting comparison screen, you’ll see a row of select boxes. You want to make sure these are configured like so:

<div class="github panel">
<div class="range-editor">
Expand Down Expand Up @@ -118,9 +110,8 @@ Another paragraph.
</div>
</div>

<article class="post-content">
<p><em><strong>username</strong> being your github username, <strong>branch</strong> being the branch you have been working on.</em></p>
_**username** being your github username, **branch** being the branch you have been working on._

<p>You should now be able to see listed below, all the changes that you wish to contribute. If everything looks as it should, click ‘<em>Create pull request</em>’.</p>
You should now be able to see listed below, all the changes that you wish to contribute. If everything looks as it should, click '*Create pull request*'.

<p>Give your pull request a title and description, then click ‘<em>Create pul request</em>’. You have now contributed your pages to the Handbook :)</p>
Give your pull request a title and description, then click '*Create pul request*'. You have now contributed your pages to the Handbook :)
Loading

0 comments on commit 1433559

Please sign in to comment.