You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/pages/contribution-guide/contrib-workflow/index.md
+2-2Lines changed: 2 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,5 @@
1
1
---
2
-
title: "Content contribution workflow"
2
+
title: "Contribution workflow"
3
3
date: 2024-04-30T14:25:09+08:00
4
4
tags: ["Contribute"]
5
5
showAuthor: false
@@ -9,7 +9,7 @@ authors:
9
9
10
10
## Overview
11
11
12
-
The content contribution diagram below shows how contributions can be done to [espressif / developer-portal][], marked as **Public Upstream**. It is Developer Portal's public GitHub repo.
12
+
The contribution diagram below shows how contributions can be done to [espressif / developer-portal][], marked as **Public Upstream**. It is Developer Portal's public GitHub repo.
Copy file name to clipboardExpand all lines: content/pages/contribution-guide/writing-content/index.md
+80-11Lines changed: 80 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,8 @@
1
1
---
2
-
title: "Content writing workflow"
2
+
title: "Writing content"
3
3
date: 2024-04-29T14:25:01+08:00
4
4
tags: ["Contribute"]
5
+
showTableOfContents: true
5
6
showAuthor: false
6
7
authors:
7
8
- "kirill-chalov"
@@ -11,7 +12,7 @@ authors:
11
12
12
13
There are the following prerequisites before you start writing content:
13
14
14
-
- Decide how you want to contribute by choosing the [content contribution workflow](../content-contrib-workflow"Content contribution workflow") and get a copy of the [espressif / developer-portal][] repo
15
+
- Decide how you want to contribute by choosing the [contribution workflow](../contrib-workflow"Contribution workflow") and get a copy of the [espressif / developer-portal][] repo
15
16
- To view the built version of the website, [install](https://gohugo.io/installation/) Hugo in your environment and go through [Getting started](https://gohugo.io/getting-started/) if required
@@ -62,7 +63,7 @@ This is totally up to you how you write the content as long as it is valuable fo
62
63
63
64
For writing and formatting conventions, the contributors at Espressif usually follow the [Espressif Manual of Style](https://mos.espressif.com/) and the *Chicago Manual of Style*. You might find these guidelines useful, but you are not required to follow them.
64
65
65
-
### Prepare a featured image
66
+
## Prepare a featured image
66
67
67
68
A featured image appears above the article's title. A nice and relevant image attracts readers like a magnet, that is why consider giving more thought to it.
68
69
@@ -81,20 +82,88 @@ A featured image can be added in the following ways from the highest to lowest p
Apart from the usual content types supported by markdown, such as visuals or code blocks, you can use other content types enabled by Hugo shortcodes. This section briefly introduces them.
92
88
93
89
If you need other types of content, either create a discussion on GitHub or offer a PR with the required functionality. It will be very much appreciated!
94
90
95
91
92
+
### Images
93
+
94
+
95
+
96
+
97
+
### Code blocks with tabs
98
+
99
+
Tabbed code blocks look neat:
100
+
101
+
{{< tabs groupId="config" >}}
102
+
{{% tab name="Linux" %}}
103
+
```md
104
+
Linux code block
105
+
```
106
+
{{% /tab %}}
107
+
{{% tab name="macOS" %}}
108
+
Update homebrew, then run:
109
+
```md
110
+
macOS code block
111
+
```
112
+
{{% /tab %}}
113
+
{{< /tabs >}}
114
+
115
+
At the same time, the markup is very simple:
116
+
117
+
````md
118
+
{{</* tabs groupId="config" */>}}
119
+
{{%/* tab name="Linux" */%}}
120
+
```md
121
+
Linux code block
122
+
```
123
+
{{%/* /tab */%}}
124
+
{{%/* tab name="macOS" */%}}
125
+
Update homebrew, then run:
126
+
```md
127
+
macOS code block
128
+
```
129
+
{{%/* /tab */%}}
130
+
{{</* /tabs */>}}
131
+
````
132
+
133
+
Some explanations:
134
+
135
+
- Use the `tabs` shortcode to create a tabbed code block
136
+
- Use the nested `tab` shortcode to create as many tabs as you need
137
+
- Within a tab, place any markdown content you want, it will be rendered like any other markdown content
138
+
139
+
For a real example, see this [page](../../../blog/build-embedded-swift-application-for-esp32c6/#building-an-example-project).
140
+
141
+
As you can see, the `tabs` shortcode has **the parameter** `groupId`. It creates association between all tabbed code blocks bearing the same `groupId` on a webpage. Once you choose a certain tab, all associated code blocks will switch to the same tab. It can be useful in tutorials covering multiple operating systems, programming lanugages, etc.
142
+
143
+
You can also easily **indent a tabbed code block**, by preceding the `tabs` and `tab` shortcodes with the required number of spaces. This is exactly what was [done][indented-tabbed-code-block] in the linked example above.
Youtube videos using [Hugo shortcodes](https://gohugo.io/content-management/shortcodes/#youtube)
163
+
164
+
96
165
## Ask for review
97
166
98
167
To publish your content on the Espressif Developer Portal, please create a discussion in [espressif / developer-portal][] invite reviewers from Espressif so that they can make sure your content is in-line with Espressif's writing conventions.
99
168
100
-
After the review is done, create a PR following the [content contribution workflow](../content-contrib-workflow "Content contribution workflow").
169
+
After the review is done, create a PR following the [contribution workflow](../contrib-workflow "Contribution workflow").
0 commit comments