Skip to content

Commit 9184a21

Browse files
skdwritingskdwriting
authored
Merge pull request #27 from anvithks/migrate-hugo
[How-to Add Blog]Added how to contribute a blog to OpenSDS blog site.
2 parents 8c7fadb + 0e467ab commit 9184a21

File tree

5 files changed

+164
-10
lines changed

5 files changed

+164
-10
lines changed

‎config.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
baseURL = "https://opensds-docs.netlify.com/"
22
languageCode = "en-US"
33
defaultContentLanguage = "en"
4+
googleAnalytics = "UA-138679091-1"
45

56
title = "OpenSDS Documentation"
67
theme = "hugo-theme-learn"

‎content/community/blog.md‎

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

‎content/community/contribute-blog/_index.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
title: Contribute to the OpenSDS Blog
3+
description: "This guide explains how to contribute an entry to the OpenSDS Blog at http://blog.opensds.io."
4+
weight: 3
5+
---
6+
{{% notice note %}}
7+
The blog website is based on Hugo/Netlify.
8+
Install Hugo version 0.55.6 from [here](https://github.com/gohugoio/hugo/releases/tag/v0.55.6) and instructions can be found [here](https://gohugo.io/getting-started/installing/)
9+
To see a locally running preview use the command `hugo server` from the doc root.
10+
The blog is based on the [Nederburg Theme](https://github.com/appernetic/hugo-nederburg-theme) for Hugo.
11+
{{% /notice %}}
12+
13+
## 1. Fork and Clone
14+
- Fork the blog repository from [here](https://github.com/opensds/blog).
15+
- Clone the fork.
16+
17+
```
18+
cd blog
19+
#The blog website uses the [Nederburg theme](https://github.com/appernetic/hugo-nederburg-theme) for Hugo. It is added as a git submodule and needs to be initialized.
20+
git submodule --init --recursive
21+
```
22+
## 2. Add writer
23+
24+
If you are going to contribute regularly you can add yourself as an author on the blog repository. In the root directory navigate to the `config.toml` file. Look for the section `[params.writers]` and add your bio. The format looks like the following:
25+
26+
```toml
27+
[params.writers]
28+
[params.writers."Anvith KS"]
29+
link = "https://example.io/"
30+
email = "your@email.com"
31+
bio = [
32+
"This is the author bio shown after posts."
33+
]
34+
facebook = "full profile url in facebook"
35+
googleplus = "full profile url in googleplus"
36+
twitter = "full profile url in twitter"
37+
linkedin = "full profile url in linkedin"
38+
stackoverflow = "full profile url in stackoverflow"
39+
instagram = "full profile url in instagram"
40+
github = "full profile url in github"
41+
pinterest = "full profile url in pinterest"
42+
```
43+
44+
Here is an example of a front matter entry for the writer defined above.
45+
46+
```toml
47+
writer = "Anvith KS"
48+
```
49+
### Alternative method to add a writer
50+
51+
Alternatively you can just add your details in the post front matter.
52+
53+
```toml
54+
...
55+
writer = "Anvith KS"
56+
writer_link = "https://example.io/"
57+
writer_email = "your@email.com"
58+
writer_bio = "Anvith is an avid blogger and the founder of <a href='https://example.io/'>Example.io</a>. This is the author bio shown after posts."
59+
writer_twitter = "https://twitter.com/<yourhandlehere>"
60+
...
61+
```
62+
63+
It will override the author in the config. If you have not added yourself to the author list then you will have to add your details to every blog entry.
64+
65+
## 3. Adding a new post
66+
67+
Navigate to the `content\post\` folder. Create a new file and follow the naming convention as `YYYYMMDD-filename.md` .
68+
At the beginning of the post add the front matter between `+++` including the `+++`. The front matter format is as follows:
69+
70+
```toml
71+
+++
72+
#If you want to keep the post in draft state set this to `true`
73+
draft = false
74+
#For the featured image visible on the post list page. Put the image in the `static/img/` folder.
75+
image = "img/orchestration-arch-design.png"
76+
#The post date in GMT +5.30
77+
date = "2019-09-17T10:30:00+05:30"
78+
#Post Title
79+
title = "OpenSDS Orchestration - Simplifying Complex Data Management Tasks"
80+
#The slug is visible in the URL and helps make the URL readable.
81+
slug = "orchestration-simplifying-complex-data-management-tasks"
82+
#Post Description. Max 200 characters.
83+
description = "To reduce manual intervention and provide ease of use, orchestration helps to streamline and optimize frequent, repeatable processes to ensure accurate and faster execution of services."
84+
#Add writers here. If the writer is already added to the config.toml file then just add a reference to the name and the details will be picked up.
85+
#Else the details will have to be added. Follow the add writer alternative method above.
86+
writer = "Himanshu, Ashit"
87+
#The blog categories. Add the categories to which the post belongs. If the category does not exist then add a new one.
88+
categories = [ "Blog", "Features", "Orchestration"]
89+
#Add related tags
90+
tags = ["orchestration"]
91+
+++
92+
```
93+
94+
## 4. Adding post excerpt
95+
96+
The post excerpt is visible in the post listing page. This content is derived from the first 200 characters of the article immediately after the end of the front matter `+++` and end with `<!-- more -->`.
97+
For example:
98+
99+
```
100+
...
101+
categories = [ "Blog", "Features", "Orchestration"]
102+
tags = ["orchestration"]
103+
# weight = 1
104+
+++
105+
106+
To reduce manual intervention and provide ease of use, Orchestration helps to streamline and optimize frequent, repeatable processes to ensure accurate and faster execution of services.
107+
<!-- more -->
108+
#Remove the space before and after `more`
109+
...
110+
```
111+
112+
![Post Excerpt](post_excerpt.png)
113+
114+
115+
116+
## 5. Adding post content
117+
118+
- Please use standard markdown formatting to write your post.
119+
- Use blockquotes to highlight sections of importance.
120+
- Avoid using first level heading (#).
121+
- Use second level headings (##) for important sections.
122+
- Use URL hyperlinking with readable titles for long URLS. for example
123+
{{% notice note %}}
124+
[Click here](https://github.com/opensds/orchestration/blob/master/docs/INSTALL.md) for the OpenSDS Orchestration Manager Installation:
125+
*instead of*
126+
Click Here [https://github.com/opensds/orchestration/blob/master/docs/INSTALL.md](https://github.com/opensds/orchestration/blob/master/docs/INSTALL.md) for the OpenSDS Orchestration Manager Installation:
127+
{{% /notice %}}
128+
- To include images in the post use the standard markdown way to display images. Place the images under the `/static/img/` folder and link using the relative path. For Example:
129+
```
130+
#Usage:
131+
![OpenSDS Orchestration Manager Architecture diagram](/img/orchestration-arch-design.png)
132+
```
133+
- Alternatively you can also use the hugo shortcode `figure`.
134+
135+
```
136+
# Usage:
137+
# Remove the space after the {{ and before the }}
138+
{{ < figure src="/img/orchestration-arch-design.png" title="OpenSDS Orchestration Manager Architecture diagram" > }}
139+
```
140+
- More Hugo Shortcodes for content management can be found [here](https://gohugo.io/content-management/shortcodes/)
141+
142+
## 6. Run a local build (optional)
143+
144+
Run the following commands in the root directory to view the site locally. You can verify the content and styling is as per the style guide before raising the PR.
145+
```
146+
hugo server
147+
```
148+
## 7. Raise a PR
149+
- After the blog is written raise a pull request to the `master` branch on the `opendsds/blog` repository.
150+
- Netlify will create a preview build and the actual page can be viewed in this preview.
151+
- The blog will be reviewed by atleast 2 reviewers which may include one technical writer and one developer.
152+
- After the blog is reviewed and merged it will be added as the latest post and can be viewed at [blog.opensds.io](http://blog.opensds.io)

‎content/community/contribute-blog/post_excerpt.png‎

263 KB
Loading

‎content/credits.en.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,3 +39,14 @@ Thanks to them <i class="fas fa-heart"></i> for making Open Source Software a be
3939

4040
{{% ghcontributors "https://api.github.com/repos/opensds/orchestration/contributors?per_page=100" %}}
4141

42+
## Documentation Contributors
43+
44+
Thanks to them <i class="fas fa-heart"></i> for making Open Source Software a better place !
45+
46+
{{% ghcontributors "https://api.github.com/repos/opensds/documentation/contributors?per_page=100" %}}
47+
48+
## Blog Contributors
49+
50+
Thanks to them <i class="fas fa-heart"></i> for making Open Source Software a better place !
51+
52+
{{% ghcontributors "https://api.github.com/repos/opensds/blog/contributors?per_page=100" %}}

0 commit comments

Comments
 (0)