-
Notifications
You must be signed in to change notification settings - Fork 681
/
Copy pathmarkdown.template
186 lines (141 loc) · 6.29 KB
/
markdown.template
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
author: AUTHOR_NAME
id: SFGUIDE_NAME
summary: This is a sample Snowflake Guide
categories: Getting-Started
environments: web
status: Published
feedback link: https://github.com/Snowflake-Labs/sfguides/issues
tags: Getting Started, Data Science, Data Engineering, Twitter
# Snowflake Guide Template
<!-- ------------------------ -->
## Overview
Duration: 1
Please use [this markdown file](https://raw.githubusercontent.com/Snowflake-Labs/sfguides/master/site/sfguides/sample.md) as a template for writing your own Snowflake Quickstarts. This example guide has elements that you will use when writing your own guides, including: code snippet highlighting, downloading files, inserting photos, and more.
It is important to include on the first page of your guide the following sections: Prerequisites, What you'll learn, What you'll need, and What you'll build. Remember, part of the purpose of a Snowflake Guide is that the reader will have **built** something by the end of the tutorial; this means that actual code needs to be included (not just pseudo-code).
The rest of this Snowflake Guide explains the steps of writing your own guide.
### Prerequisites
- Familiarity with Markdown syntax
### What You’ll Learn
- how to set the metadata for a guide (category, author, id, etc)
- how to set the amount of time each slide will take to finish
- how to include code snippets
- how to hyperlink items
- how to include images
### What You’ll Need
- A [GitHub](https://github.com/) Account
- [VSCode](https://code.visualstudio.com/download) Installed
- [NodeJS](https://nodejs.org/en/download/) Installed
- [GoLang](https://golang.org/doc/install) Installed
### What You’ll Build
- A Snowflake Guide
<!-- ------------------------ -->
## Metadata Configuration
Duration: 2
It is important to set the correct metadata for your Snowflake Guide. The metadata contains all the information required for listing and publishing your guide and includes the following:
- **summary**: This is a sample Snowflake Guide
- This should be a short, 1 sentence description of your guide. This will be visible on the main landing page.
- **id**: sample
- make sure to match the id here with the name of the file, all one word.
- **categories**: data-science
- You can have multiple categories, but the first one listed is used for the icon.
- **environments**: web
- `web` is default. If this will be published for a specific event or conference, include it here.
- **status**: Published
- (`Draft`, `Published`, `Deprecated`, `Hidden`) to indicate the progress and whether the sfguide is ready to be published. `Hidden` implies the sfguide is for restricted use, should be available only by direct URL, and should not appear on the main landing page.
- **feedback link**: https://github.com/Snowflake-Labs/sfguides/issues
- **tags**: Getting Started, Data Science, Twitter
- Add relevant tags to make your sfguide easily found and SEO friendly.
- **authors**: Daniel Myers
- Indicate the author(s) of this specific sfguide.
---
You can see the source metadata for this guide you are reading now, on [the github repo](https://raw.githubusercontent.com/Snowflake-Labs/sfguides/master/site/sfguides/sample.md).
<!-- ------------------------ -->
## Creating a Step
Duration: 2
A single sfguide consists of multiple steps. These steps are defined in Markdown using Header 2 tag `##`.
```markdown
## Step 1 Title
Duration: 3
All the content for the step goes here.
## Step 2 Title
Duration: 1
All the content for the step goes here.
```
To indicate how long each step will take, set the `Duration` under the step title (i.e. `##`) to an integer. The integers refer to minutes. If you set `Duration: 4` then a particular step will take 4 minutes to complete.
The total sfguide completion time is calculated automatically for you and will be displayed on the landing page.
<!-- ------------------------ -->
## Code Snippets, Info Boxes, and Tables
Duration: 2
Look at the [markdown source for this sfguide](https://raw.githubusercontent.com/Snowflake-Labs/sfguides/master/site/sfguides/sample.md) to see how to use markdown to generate code snippets, info boxes, and download buttons.
### JavaScript
```javascript
{
key1: "string",
key2: integer,
key3: "string"
}
```
### Java
```java
for (statement 1; statement 2; statement 3) {
// code block to be executed
}
```
### Info Boxes
> aside positive
>
> This will appear in a positive info box.
> aside negative
>
> This will appear in a negative info box.
### Buttons
<button>
[This is a download button](link.com)
</button>
### Tables
<table>
<thead>
<tr>
<th colspan="2"> **The table header** </th>
</tr>
</thead>
<tbody>
<tr>
<td>The table body</td>
<td>with two columns</td>
</tr>
</tbody>
</table>
### Hyperlinking
[Youtube - Halsey Playlists](https://www.youtube.com/user/iamhalsey/playlists)
<!-- ------------------------ -->
## Images, Videos, and Surveys, and iFrames
Duration: 2
Look at the [markdown source for this guide](https://raw.githubusercontent.com/Snowflake-Labs/sfguides/master/site/sfguides/sample.md) to see how to use markdown to generate these elements.
### Images
### Videos
Videos from youtube can be directly embedded:
<video id="KmeiFXrZucE"></video>
### Inline Surveys
<form>
<name>How do you rate yourself as a user of Snowflake?</name>
<input type="radio" value="Beginner">
<input type="radio" value="Intermediate">
<input type="radio" value="Advanced">
</form>
### Embed an iframe
<!-- ------------------------ -->
## Conclusion And Resources
Duration: 1
At the end of your Snowflake Guide, always have a clear call to action (CTA). This CTA could be a link to the docs pages, links to videos on youtube, a GitHub repo link, etc.
If you want to learn more about Snowflake Guide formatting, checkout the official documentation here: [Formatting Guide](https://github.com/googlecodelabs/tools/blob/master/FORMAT-GUIDE.md)
### What You Learned
- creating steps and setting duration
- adding code snippets
- embedding images, videos, and surveys
- importing other markdown files
### Related Resources
- <link to github code repo>
- <link to documentation>