Skip to content

Commit 339b759

Browse files
alexcualexcu
committed
FIX: Add updated guide on how to publish guides using the new system
1 parent 22b3adc commit 339b759

File tree

2 files changed

+155
-63
lines changed

2 files changed

+155
-63
lines changed

‎source/articles/contributing/index.html.md‎

Lines changed: 0 additions & 63 deletions
This file was deleted.

‎source/articles/contributing/index.html.md.erb‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,155 @@
1+
# Writing a SplashKit Guide
2+
3+
This tutorial will cover the details of how to write a SplashKit guide for the SplashKit website.
4+
5+
You will need:
6+
7+
1. a [GitHub](http://github.com) account,
8+
2. a Ruby development environment (v2.3.1) to build the website,
9+
3. an awesome idea for a guide!
10+
11+
## Getting Ready
12+
13+
In order to test your guide in the SplashKit website, you need to download the source code for the website. To do this, make sure you are logged into GitHub, and then [create a fork](http://github.com/splashkit/splashkit.io/fork) of the SplashKit.io website repository onto your own personal GitHub account.
14+
15+
Once you have forked the website repository, you should then [clone your fork](https://help.github.com/articles/cloning-a-repository/) of the repository to your local machine by selecting "clone or download" and copying the link. You can do this via the `git clone <link>` command in the terminal, or by using [GitHub Desktop](https://desktop.github.com).
16+
17+
Once you have cloned your forked repository, follow the instructions posted in the website's [readme](https://github.com/splashkit/splashkit.io/blob/master/README.md).
18+
19+
## Creating The Guide
20+
21+
To create a new guide, navigate to the directory where you cloned the repository:
22+
23+
```
24+
cd /path/to/splashkit.io
25+
```
26+
27+
Guides are categorised using a _tag_, which must relate to a member in the API group. The following keys can be used to relate your article to a specific API group:
28+
29+
<% data.api.keys.each do |key| %>
30+
- **`<%= key %>`**: <%= key.to_human_case %>
31+
<% end %>
32+
33+
Once you have decided a name for your guide and which API group(s) it should relate, execute the following command:
34+
35+
```
36+
bundle exec middleman article "[Name of Guide]" -t [tags]
37+
```
38+
39+
You can associate multiple tags to one guide by separating tags using a comma. For example, if you wanted to write a `graphics` and `window`-related guide entitled "Drawing simple shapes", you would execute:
40+
41+
```
42+
bundle exec middleman article "Drawing simple shapes" -t graphics,window
43+
```
44+
45+
Once you execute this command, you will see that the guide you have named appears under `source/articles/guides` using the current day's date. For example, the command above would create `source/articles/guides/20XX-XX-XX-drawing-simple-shapes.html.md`.
46+
47+
## Adding Required Frontmatter
48+
49+
Open this file in a text editor and you will see the following:
50+
51+
```yaml
52+
---
53+
54+
title: Drawing simple shapes
55+
date: 2017-12-11 06:44 UTC
56+
tags: graphics,window
57+
58+
---
59+
```
60+
61+
The data separated by the three dashes (`---`) is known as the _frontmatter_ of the guide. This contains metadata about the guide, which (by default) includes the guide name, date created, and associated tags.
62+
63+
<div class="alert alert-warning">
64+
<strong>Note:</strong> You <strong>must</strong> add the following keys to the frontmatter:
65+
<ul>
66+
<li>
67+
<strong><code>author</code></strong>:
68+
your full name,
69+
</li>
70+
<li>
71+
<strong><code>author_url</code></strong>:
72+
a URL to your GitHub profile or personal website,
73+
</li>
74+
<li>
75+
<strong><code>summary</code></strong>:
76+
a summary of the guide that should be no more than two to three lines and should embody the gist of the guide,
77+
</li>
78+
<li>
79+
<strong><code>related_funcs</code></strong>:
80+
a list of related functions in snake_case.
81+
</li>
82+
</ul>
83+
<strong>If you do not do this you may break the API documentation generation!</strong>
84+
</div>
85+
86+
We suggest you copy and paste the following example to add it to the frontmatter to ensure no mistakes:
87+
88+
```yaml
89+
---
90+
91+
title: Drawing simple shapes
92+
date: 2017-12-11 06:44 UTC
93+
tags: graphics,window
94+
author: Fred Smith
95+
author_url: http://github.com/fsmith
96+
summary: |
97+
This guide discusses how you can open a window to draw some simple
98+
shapes in order to start playing around with graphics in SplashKit.
99+
related_funcs:
100+
- create_window
101+
- draw_rectangle
102+
- refresh_screen
103+
- clear_screen
104+
105+
---
106+
107+
```
108+
109+
If you are unsure what functions keys to use, refer to the C++ snake_case name in the website. For example, for the "Free Music" function:
110+
111+
![Example of name to use for function](https://i.imgur.com/TiTmcd3.png)
112+
113+
## Write the guide
114+
115+
Underneath the bottom three dashes, you may begin writing your guide using [Github-flavoured Markdown](https://guides.github.com/features/mastering-markdown/). You won't need to add the title of the guide as a Heading 1 (`<h1>` or `#`) as this is automatically added for you.
116+
117+
<div class="alert alert-warning">
118+
<strong>Note:</strong> When writing your guide, ensure you only use
119+
Heading 2 to Heading 6 (<code>&lt;h2&gt;</code> ... <code>&lt;h6&gt;</code> or <code>##</code> ... <code>######</code>).
120+
This is because Heading 1 is reserved for the guide's title.
121+
</div>
122+
123+
Remember to keep the language friendly, include examples and ensure it is high quality.
124+
125+
If you would like to include images in your guide, **host them on [Imgur](http://imgur.com)** as this will ensure they exist permanently (unlike temporary image hosting services such as [puush](http://puush.me/)).
126+
127+
## Test the guide
128+
129+
After you have finished writing, it's time to make sure everything looks right!
130+
131+
From your terminal, where you created the guide, run the following command to start running the website locally:
132+
133+
```
134+
bundle exec middleman
135+
```
136+
137+
Now, visit [`http://localhost:4567`](http://localhost:4567) to see the website.
138+
139+
Run through the following checklist to make sure:
140+
141+
1. that you can navigate to the guides and see your guide your guide indexed in the _right_ API groups that you tagged your guide under,
142+
2. make sure it all looks good (i.e., no visual errors),
143+
3. make sure that relevant API function links appear under the respective functions in the API documentation. For example, if you wrote a `json`-tagged guide related to the `create_json` function, you would want to see the guides appear under the JSON API docs and the respective function:
144+
![JSON Guide Home](https://i.imgur.com/cPKwNgx.png)
145+
![JSON Guide Function](https://i.imgur.com/KNhJIJn.png)
146+
147+
## Merging your guides into the SplashKit website
148+
149+
If it's all looking good, it's time to submit a "pull request" so that a core member of the SplashKit team can review your proposed guide and get it published.
150+
151+
To do this, push your changes via GitHub, and visit the GitHub webiste for your fork. View this [GitHub tutorial](https://help.github.com/guides/creating-a-pull-request/) for more details on how to do this. A member of the SplashKit team will view your guide, give feedback, and otherwise make sure everything looks good. Finally, they will then publish your guide!
152+
153+
SplashKit is completely open source, and free to use &mdash; any contributions to the project are appreciated!
154+
155+
If at any stage of this process you run into any issues, feel free to raise an issue on GitHub.

0 commit comments

Comments
 (0)