├── .gitignore
├── demo.md
├── package.json
├── other-examples
    └── top-right-md-heading.md
├── demo.js
├── svg-with-css.svg
└── README.md


/.gitignore:
--------------------------------------------------------------------------------
1 | node_modules
2 | 


--------------------------------------------------------------------------------
/demo.md:
--------------------------------------------------------------------------------
1 | # MD magic DEMO
2 | 
3 | <!-- AUTO-GENERATED-CONTENT:START (customTransform:optionOne=hi&optionOne=DUDE) -->
4 | demo text
5 | <!-- AUTO-GENERATED-CONTENT:END -->
6 | 


--------------------------------------------------------------------------------
/package.json:
--------------------------------------------------------------------------------
 1 | {
 2 |   "name": "advanced-markdown",
 3 |   "version": "0.0.1",
 4 |   "description": "Markdown presentation",
 5 |   "main": "index.js",
 6 |   "author": "DavidWells",
 7 |   "license": "MIT",
 8 |   "scripts": {
 9 |     "demo": "node demo.js",
10 |     "docs": "md-magic --path 'README.md' --ignore 'node_modules'"
11 |   },
12 |   "homepage": "https://github.com/DavidWells/advanced-markdown#readme",
13 |   "devDependencies": {
14 |     "markdown-magic": "^2.3.2"
15 |   }
16 | }
17 | 


--------------------------------------------------------------------------------
/other-examples/top-right-md-heading.md:
--------------------------------------------------------------------------------
1 | <p align="right">01/01/2000</p>
2 | 
3 | Text on the top right corner. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
4 | Ut enim blandit volutpat maecenas volutpat blandit aliquam etiam. Luctus accumsan tortor posuere ac. Euismod elementum nisi quis eleifend quam. 
5 | Hendrerit dolor magna eget est lorem ipsum dolor. Tincidunt tortor aliquam nulla facilisi cras fermentum odio eu feugiat. 
6 | Quis viverra nibh cras pulvinar. Hendrerit gravida rutrum quisque non tellus. 
7 | Viverra ipsum nunc aliquet bibendum. 
8 | Purus ut faucibus pulvinar elementum integer enim neque volutpat ac 
9 | 


--------------------------------------------------------------------------------
/demo.js:
--------------------------------------------------------------------------------
 1 | const fs = require('fs')
 2 | const path = require('path')
 3 | const markdownMagic = require('markdown-magic')
 4 | 
 5 | const config = {
 6 |   transforms: {
 7 |     /* Match AUTO-GENERATED-CONTENT (customTransform:optionOne=hi&optionOne=DUDE) */
 8 |     customTransform(content, options) {
 9 |       console.log('original innerContent', content)
10 |       console.log(options) // { optionOne: hi, optionOne: DUDE}
11 |       return `This will replace all the contents of inside the comment ${options.optionOne}`
12 |     },
13 |     // /* Match AUTO-GENERATED-CONTENT (RENDERDOCS:path=../file.js) */
14 |     // RENDERDOCS(content, options) {
15 |     //   const contents = fs.readFileSync(options.path, 'utf8')
16 |     //   const docBlocs = require('dox').parseComments(contents, { raw: true, skipSingleStar: true })
17 |     //   let updatedContent = ''
18 |     //   docBlocs.forEach((data) => {
19 |     //     updatedContent += `${data.description.full}\n\n`
20 |     //   })
21 |     //   return updatedContent.replace(/^\s+|\s+$/g, '')
22 |     // },
23 |     // pluginExample: require('./plugin-example')({ addNewLine: true }),
24 |     // count: require('markdown-magic-wordcount'),
25 |     // github: require('markdown-magic-github-contributors')
26 |   }
27 | }
28 | 
29 | const markdownPath = path.join(__dirname, 'demo.md')
30 | markdownMagic(markdownPath, config, function(err, output) {
31 |   // output is array of file information
32 |   console.log('FINISHED')
33 | })
34 | 


--------------------------------------------------------------------------------
/svg-with-css.svg:
--------------------------------------------------------------------------------
 1 | <svg fill="none" viewBox="0 0 800 400" width="800" height="400" xmlns="http://www.w3.org/2000/svg">
 2 | 	<foreignObject width="100%" height="100%">
 3 | 		<div xmlns="http://www.w3.org/1999/xhtml">
 4 | 			<style>
 5 | 				@keyframes rotate {
 6 | 					0% {
 7 | 						transform: rotate(3deg);
 8 | 					}
 9 | 					100% {
10 | 						transform: rotate(-3deg);
11 | 					}
12 | 				}
13 | 				@keyframes gradientBackground {
14 | 					0% {
15 | 						background-position: 0% 50%;
16 | 					}
17 | 					50% {
18 | 						background-position: 100% 50%;
19 | 					}
20 | 					100% {
21 | 						background-position: 0% 50%;
22 | 					}
23 | 				}
24 | 				@keyframes fadeIn {
25 | 					0% {
26 | 						opacity: 0;
27 | 					}
28 | 					66% {
29 | 						opacity: 0;
30 | 					}
31 | 					100% {
32 | 						opacity: 1;
33 | 					}
34 | 				}
35 | 				.container {
36 | 					font-family:
37 | 						system-ui,
38 | 						-apple-system,
39 | 						'Segoe UI',
40 | 						Roboto,
41 | 						Helvetica,
42 | 						Arial,
43 | 						sans-serif,
44 | 						'Apple Color Emoji',
45 | 						'Segoe UI Emoji';
46 | 					display: flex;
47 | 					flex-direction: column;
48 | 					align-items: center;
49 | 					justify-content: center;
50 | 					margin: 0;
51 | 					width: 100%;
52 | 					height: 400px;
53 | 					background: linear-gradient(-45deg, #fc5c7d, #6a82fb, #05dfd7);
54 | 					background-size: 600% 400%;
55 | 					animation: gradientBackground 10s ease infinite;
56 | 					border-radius: 10px;
57 | 					color: white;
58 | 					text-align: center;
59 | 				}
60 | 				h1 {
61 | 					font-size: 50px;
62 | 					line-height: 1.3;
63 | 					letter-spacing: 5px;
64 | 					text-transform: uppercase;
65 | 					text-shadow:
66 | 						0 1px 0 #efefef,
67 | 						0 2px 0 #efefef,
68 | 						0 3px 0 #efefef,
69 | 						0 4px 0 #efefef,
70 | 						0 12px 5px rgba(0, 0, 0, 0.1);
71 | 					animation: rotate ease-in-out 1s infinite alternate;
72 | 				}
73 | 				p {
74 | 					font-size: 20px;
75 | 					text-shadow: 0 1px 0 #efefef;
76 | 					animation: 5s ease 0s normal forwards 1 fadeIn;
77 | 				}
78 | 			</style>
79 | 			<div class="container">
80 | 				<h1>Made with HTML &amp; CSS<br/>not an animated GIF</h1>
81 | 				<p>Click to see the source</p>
82 | 			</div>
83 | 		</div>
84 | 	</foreignObject>
85 | </svg>
86 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # Advanced Markdown Guide
  2 | 
  3 | [Slides -> github.com/DavidWells/advanced-markdown](https://github.com/DavidWells/advanced-markdown/)
  4 | 
  5 | ## Table of Contents
  6 | <!-- AUTO-GENERATED-CONTENT:START (TOC:collapse=true&collapseText="Click to expand") -->
  7 | <details>
  8 | <summary>"Click to expand"</summary>
  9 | 
 10 | - [Why markdown?](#why-markdown)
 11 | - [Markdown basics](#markdown-basics)
 12 | - [Advanced Formatting tips](#advanced-formatting-tips)
 13 |   - [`left` alignment](#left-alignment)
 14 |   - [`right` alignment](#right-alignment)
 15 |   - [`center` alignment example](#center-alignment-example)
 16 |   - [`collapse` Sections](#collapse-sections)
 17 |   - [`additional links`](#additional-links)
 18 |   - [Badges](#badges)
 19 | - [Useful packages](#useful-packages)
 20 | - [Useful utilities](#useful-utilities)
 21 | - [How Serverless uses markdown](#how-serverless-uses-markdown)
 22 |   - [DEMO](#demo)
 23 | - [Other Markdown Resources](#other-markdown-resources)
 24 | 
 25 | </details>
 26 | <!-- AUTO-GENERATED-CONTENT:END -->
 27 | 
 28 | ## Why markdown?
 29 | 
 30 | Markdown is a universal doc format that is easy to write and easy to add to a version control system.
 31 | 
 32 | - **Open** - Anyone can submit content, fix typos & update anything via pull requests
 33 | - **Version control** - Roll back & see the history of any given post
 34 | - **No CMS lock in** - We can easily port to any static site generator
 35 | - **It's just simple** - No user accounts to manage, no CMS software to upgrade, no plugins to install.
 36 | 
 37 | ---
 38 | 
 39 | ## Markdown basics
 40 | 
 41 | The basics of markdown can be found [here](https://guides.github.com/features/mastering-markdown/) & [here](https://daringfireball.net/projects/markdown/). Super easy!
 42 | 
 43 | ### Image with alt & title
 44 | 
 45 | ```
 46 | ![Alt text](/path/to/img.jpg "image title")
 47 | ```
 48 | 
 49 | ## Advanced Formatting tips
 50 | 
 51 | ### `left` alignment
 52 | 
 53 | <img align="left" width="100" height="100" src="https://github.com/user-attachments/assets/6c9db87a-60fb-4169-86b3-2c74c8f3bda6">
 54 | 
 55 | This is the code you need to align images to the left:
 56 | ```
 57 | <img align="left" width="100" height="100" src="https://picsum.photos/100/100">
 58 | ```
 59 | 
 60 | ---
 61 | 
 62 | ### `right` alignment
 63 | 
 64 | <img align="right" width="100" height="100" src="https://github.com/user-attachments/assets/6c9db87a-60fb-4169-86b3-2c74c8f3bda6">
 65 | 
 66 | This is the code you need to align images to the right:
 67 | ```
 68 | <img align="right" width="100" height="100" src="https://picsum.photos/100/100">
 69 | ```
 70 | 
 71 | ---
 72 | 
 73 | ### `center` alignment example
 74 | 
 75 | <p align="center">
 76 |   <img width="460" height="300" src="https://github.com/user-attachments/assets/313f519d-2d49-4b86-af1f-be2b3c299871">
 77 | </p>
 78 | 
 79 | ```
 80 | <p align="center">
 81 |   <img width="460" height="300" src="https://picsum.photos/460/300">
 82 | </p>
 83 | ```
 84 | 
 85 | ---
 86 | 
 87 | ### Horizontal images no gap
 88 | 
 89 | via [comment](https://gist.github.com/DavidWells/7d2e0e1bc78f4ac59a123ddf8b74932d?permalink_comment_id=4536101#gistcomment-4536101)
 90 | 
 91 | ```html
 92 | <p>
 93 |     <img src="https://picsum.photos/100/100" >
 94 |     <img src="https://picsum.photos/100/100" >
 95 | </p>
 96 | ```
 97 | 
 98 | <p>
 99 |     <img src="https://picsum.photos/100/100" >
100 |     <img src="https://picsum.photos/100/100" >
101 | </p>
102 | 
103 | ---
104 | 
105 | ### Horizontal images with gap
106 | 
107 | With `hspace` property you can set horizontal (left and right) padding for an image
108 | 
109 | ```html
110 | <p>
111 |     <img src="https://picsum.photos/100/100" hspace="10" >
112 |     <img src="https://picsum.photos/100/100" hspace="10" >
113 | </p>
114 | ```
115 | 
116 | <p>
117 |     <img src="https://picsum.photos/100/100" hspace="10" >
118 |     <img src="https://picsum.photos/100/100" hspace="10" >
119 | </p>
120 | 
121 | ---
122 | 
123 | ###  Vertical images with gap
124 | 
125 | We also have a property "vspace", which does what it sounds like, add vertical spacing. But it doesn't seem to work on GitHub, unlike VSCode's buit in markdown viewer. So probably just add a `<p>` tag in between. 
126 | 
127 | ```html
128 | <p>
129 |     <img src="https://picsum.photos/500/100" >
130 |     <p>
131 |     <img src="https://picsum.photos/500/100" >
132 |     <p>
133 |     <img src="https://picsum.photos/500/100" >
134 | </p>
135 | ```
136 | 
137 | <p>
138 |     <img src="https://picsum.photos/500/100"  >
139 |     <p>
140 |     <img src="https://picsum.photos/500/100" >
141 |     <p>
142 |     <img src="https://picsum.photos/500/100" >
143 | </p>
144 | 
145 | ---
146 | 
147 | ### Adding video
148 | 
149 | To add video you need to upload your video file and reference it inline
150 | 
151 | ```
152 | https://user-images.githubusercontent.com/1702215/158075475-c23004ab-827a-45ad-bdba-aee29ac5b582.mp4
153 | ```
154 | 
155 | Example:
156 | 
157 | https://user-images.githubusercontent.com/1702215/158075475-c23004ab-827a-45ad-bdba-aee29ac5b582.mp4
158 | 
159 | ### light/dark mode images
160 | 
161 | Tip via this [tweet](https://twitter.com/stefanjudis/status/1465775940034781186). Swap out images based on theme settings
162 | 
163 | ```
164 | ![Logo](./dark.png#gh-dark-mode-only)
165 | ![Logo](./light.png#gh-light-mode-only)
166 | ```
167 | 
168 | ### Using [footnotes](https://github.blog/changelog/2021-09-30-footnotes-now-supported-in-markdown-fields/)
169 | 
170 | Here is a simple footnote[^example]. With some additional text after it.
171 | 
172 | [^example]: Example footnote
173 | 
174 | ```
175 | Here is a simple footnote[^1]. With some additional text after it.
176 | 
177 | [^1]: My reference.
178 | ````
179 | 
180 | ### Strikethru text in markdown
181 | 
182 | ~~text with line through it~~
183 | 
184 | ```
185 | ~~text with line through it~~
186 | ```
187 | 
188 | ### Tiny text in markdown
189 | 
190 | Normal text here.
191 | 
192 | <sup><sub>Tiny text is here. Awwwww its so cuteeeeeeeeeee</sub></sup>
193 | 
194 | **How?**
195 | 
196 | ```
197 | <sup><sub>Add your tiny text</sub></sup>
198 | ```
199 | 
200 | ### Text box
201 | 
202 | Add a box with contents to markdown
203 | 
204 | <div align="center">
205 | <table>
206 | <tbody>
207 | <td align="center">
208 | <img width="2000" height="0"><br>
209 | <sub>This is text in the box. Much wow</sub><br>
210 | <img width="2000" height="0">
211 | </td>
212 | </tbody>
213 | </table>
214 | </div>
215 | 
216 | ```
217 | <div align="center">
218 | <table>
219 | <tbody>
220 | <td align="center">
221 | <img width="2000" height="0"><br>
222 | <sub>This is text in the box. Much wow</sub><br>
223 | <img width="2000" height="0">
224 | </td>
225 | </tbody>
226 | </table>
227 | </div>
228 | ```
229 | 
230 | ### `collapse` Sections
231 | 
232 | Collapsing large blocks of text can make your markdown much easier to digest
233 | 
234 | <details>
235 | <summary>"Click to expand"</summary>
236 | this is hidden block
237 | </details>
238 | 
239 | ```
240 | <details>
241 | <summary>"Click to expand"</summary>
242 | this is hidden
243 | </details>
244 | ```
245 | 
246 | Collapsing large blocks of Markdown text
247 | 
248 | <details>
249 | <summary>To make sure markdown is rendered correctly in the collapsed section...</summary>
250 | 
251 |  1. Put an **empty line** after the `<summary>` block.
252 |  2. *Insert your markdown syntax*
253 |  3. Put an **empty line** before the `</details>` tag
254 |  
255 | </details>
256 | 
257 | ```
258 | <details>
259 | <summary>To make sure markdown is rendered correctly in the collapsed section...</summary>
260 | 
261 |  1. Put an **empty line** after the `<summary>` block.
262 |  2. *Insert your markdown syntax*
263 |  3. Put an **empty line** before the `</details>` tag
264 |  
265 | </details>
266 | ```
267 | 
268 | ---
269 | 
270 | ## Mermaid Charts
271 | 
272 | You can add fancy zoomable charts
273 | 
274 | ```mermaid
275 | %%{ init: { "er" : { "layoutDirection" : "LR" } } }%%
276 | erDiagram
277 |     User ||--o{ Vote : submits
278 |     Vote o{--|| Link : on
279 |     Link o{--|| Score : has
280 | ```
281 | 
282 | Here's another cool example of a [sequence diagram](https://github.com/tom-barone/discontent/blob/431a6bd39216fd1f3018804a1dbe0967e22adfc5/docs/architecture.md#sequence-diagrams)
283 | 
284 | ```mermaid
285 | sequenceDiagram
286 |     actor Extension
287 |     participant API
288 |     participant Database
289 |     Extension->>API: POST /vote {link, vote, user_id}`
290 | 		activate API
291 | 		API->>API: Validate parameters
292 |     alt Invalid parameters
293 |         API->>Extension: Error: Invalid parameters
294 |     end
295 | 		API->>Database: Check user history & settings. GetBatchItems(___________)
296 | 		Note over API,Database: Voting disabled? GetItem(PK=settings, SK=settings)
297 | 		Note over API,Database: Too many votes? GetItem(PK=date, SK=user_id)
298 | 		Note over API,Database: User exists? User banned? GetItem(PK=user_id, SK=user_id)
299 | 		Note over API,Database: Already voted? GetItem(PK=link, SK=user_id)
300 | 		activate Database
301 |     alt Database Error
302 |         Database->>API: Database Error (connection / server...)
303 |         API->>Extension: Server Error
304 |     end
305 | 		Database->>API: Return UserHistory & Settings
306 | 		deactivate Database
307 | 		API->>API: Check user history & Settings
308 |     alt Failed
309 |         API->>Extension: 403 Forbidden: Too many votes / banned / voting disabled
310 |     end
311 | 		activate Database
312 | 		API->>Database: Submit vote. BatchWriteItems(_________________)
313 |     alt If user does not exist
314 | 		Note over API,Database: Put(PK=user_id, SK=user_id | not_banned,created_at)
315 | 		Note over API,Database: <run [First time user voting on link]>
316 | 		else First time user voting on link
317 | 		Note over API,Database: Put(PK=link, SK=user_id | vote)
318 | 		Note over API,Database: Update(PK=link, SK=link | count_of_votes++, sum_of_votes+=vote)
319 | 		Note over API,Database: -- Add history
320 | 		Note over API,Database: Update(PK=day, SK=link | count++, sum+=vote)
321 | 		Note over API,Database: Update(PK=day, SK=user | count++, sum+=vote)
322 |     else If user already voted on link
323 | 		Note over API,Database: Put(PK=link, SK=user_id | vote)
324 | 		Note over API,Database: Update(PK=link, SK=link | sum_of_votes+=(-old_vote+new_vote))
325 | 		Note over API,Database: -- Undo old history
326 | 		Note over API,Database: Update(PK=old_day, SK=link | count--, sum-=old_vote)
327 | 		Note over API,Database: Update(PK=old_day, SK=user | count--, sum-=old_vote)
328 | 		Note over API,Database: -- Add history
329 | 		Note over API,Database: Update(PK=day, SK=link | count++, sum+=vote)
330 | 		Note over API,Database: Update(PK=day, SK=user | count++, sum+=vote)
331 | 		end
332 | 		activate Database
333 |     alt Database Error
334 |         Database->>API: Database Error (connection / server...)
335 |         API->>Extension: Server Error
336 |     end
337 | 		Database->>API: Return success
338 | 		API->>Extension: Return success
339 |     deactivate Database
340 |     deactivate API
341 | ```
342 | 
343 | ---
344 | 
345 | ### Call outs
346 | 
347 | Add call outs in [markdown](https://github.com/community/community/discussions/16925)
348 | 
349 | > [!NOTE]  
350 | > Highlights information that users should take into account, even when skimming.
351 | 
352 | > [!TIP]
353 | > Optional information to help a user be more successful.
354 | 
355 | > [!IMPORTANT]  
356 | > Crucial information necessary for users to succeed.
357 | 
358 | > [!WARNING]  
359 | > Critical content demanding immediate user attention due to potential risks.
360 | 
361 | > [!CAUTION]
362 | > Negative potential consequences of an action.
363 | 
364 | ```
365 | > [!NOTE]  
366 | > Highlights information that users should take into account, even when skimming.
367 | 
368 | > [!TIP]
369 | > Optional information to help a user be more successful.
370 | 
371 | > [!IMPORTANT]  
372 | > Crucial information necessary for users to succeed.
373 | 
374 | > [!WARNING]  
375 | > Critical content demanding immediate user attention due to potential risks.
376 | 
377 | > [!CAUTION]
378 | > Negative potential consequences of an action.
379 | ```
380 | 
381 | ### Emojis
382 | 
383 | See a full list of [markdown emojis here](https://gist.github.com/rxaviers/7360908)
384 | 
385 | ### `additional links`
386 | 
387 | [Website](http://www.serverless.com) • [Email Updates](http://eepurl.com/b8dv4P) • [Gitter](https://gitter.im/serverless/serverless) • [Forum](http://forum.serverless.com) • [Meetups](https://github.com/serverless-meetups/main) • [Twitter](https://twitter.com/goserverless) • [Facebook](https://www.facebook.com/serverless) • [Contact Us](mailto:hello@serverless.com)
388 | 
389 | ```
390 | [Website](http://www.serverless.com) • [Email Updates](http://eepurl.com/b8dv4P) • [Gitter](https://gitter.im/serverless/serverless) • [Forum](http://forum.serverless.com) • [Meetups](https://github.com/serverless-meetups/main) • [Twitter](https://twitter.com/goserverless) • [Facebook](https://www.facebook.com/serverless) • [Contact Us](mailto:hello@serverless.com)
391 | ```
392 | 
393 | ---
394 | 
395 | ### Badges
396 | 
397 | <div align="center">
398 | 
399 | [![CI](https://github.com/fastify/fastify/workflows/ci/badge.svg)](https://github.com/fastify/fastify/actions/workflows/ci.yml)
400 | [![Package Manager CI](https://github.com/fastify/fastify/workflows/package-manager-ci/badge.svg)](https://github.com/fastify/fastify/actions/workflows/package-manager-ci.yml)
401 | [![Web SIte](https://github.com/fastify/fastify/workflows/website/badge.svg)](https://github.com/fastify/fastify/actions/workflows/website.yml)
402 | [![Known Vulnerabilities](https://snyk.io/test/github/fastify/fastify/badge.svg)](https://snyk.io/test/github/fastify/fastify)
403 | [![Coverage Status](https://coveralls.io/repos/github/fastify/fastify/badge.svg?branch=main)](https://coveralls.io/github/fastify/fastify?branch=main)
404 | [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
405 | 
406 | </div>
407 | 
408 | ```
409 | <div align="center">
410 | 
411 | [![CI](https://github.com/fastify/fastify/workflows/ci/badge.svg)](https://github.com/fastify/fastify/actions/workflows/ci.yml)
412 | [![Package Manager CI](https://github.com/fastify/fastify/workflows/package-manager-ci/badge.svg)](https://github.com/fastify/fastify/actions/workflows/package-manager-ci.yml)
413 | [![Web SIte](https://github.com/fastify/fastify/workflows/website/badge.svg)](https://github.com/fastify/fastify/actions/workflows/website.yml)
414 | [![Known Vulnerabilities](https://snyk.io/test/github/fastify/fastify/badge.svg)](https://snyk.io/test/github/fastify/fastify)
415 | [![Coverage Status](https://coveralls.io/repos/github/fastify/fastify/badge.svg?branch=main)](https://coveralls.io/github/fastify/fastify?branch=main)
416 | [![js-standard-style](https://img.shields.io/badge/code%20style-standard-brightgreen.svg?style=flat)](https://standardjs.com/)
417 | 
418 | </div>
419 | ```
420 | 
421 | ---
422 | 
423 | ### Nice looking file tree
424 | 
425 | For whatever [reason](https://twitter.com/alexdotjs/status/1421015442286596100) the `graphql` syntax will nicely highlight file trees like below:
426 | 
427 | ```graphql
428 | # Code & components for pages
429 | ./src/* 
430 |   ├─ src/assets - # Minified images, fonts, icon files
431 |   ├─ src/components - # Individual smaller components
432 |   ├─ src/fragments - # Larger chunks of a page composed of multiple components
433 |   ├─ src/layouts - # Page layouts used for different types of pages composed of components and fragments
434 |   ├─ src/page - # Custom pages or pages composed of layouts with hardcoded data components, fragments, & layouts
435 |   ├─ src/pages/* - # Next.js file based routing
436 |   │  ├─ _app.js - # next.js app entry point
437 |   │  ├─ _document.js - # next.js document wrapper
438 |   │  ├─ global.css - #  Global CSS styles
439 |   │  └─ Everything else... - # File based routing
440 |   └─ src/utils - # Utility functions used in various places
441 | ```
442 | 
443 | ### Using CSS in Readme
444 | 
445 | Use HTML/CSS in a readme via an SVG! [source](https://github.com/sindresorhus/css-in-readme-like-wat)
446 | 
447 | <div align="center">
448 |   <br>
449 |   <a href="https://github.com/DavidWells/advanced-markdown/blame/master/svg-with-css.svg">
450 |      <img alt="Click to see the source" height="400" src="svg-with-css.svg" width="800" />
451 |   </a>
452 |   <br>
453 | </div>
454 | 
455 | The above image is embedded like so:
456 | 
457 | ```html
458 | <div align="center">
459 |   <br/>
460 |   <a href="https://github.com/DavidWells/advanced-markdown/blame/master/svg-with-css.svg">
461 |     <img alt="Click to see the source" height="400" src="svg-with-css.svg" width="800" />
462 |   </a>
463 |   <br/>
464 | </div>
465 | ```
466 | 
467 | ---
468 | 
469 | ## Useful packages
470 | 
471 | 1. [gray-matter](https://www.npmjs.com/package/gray-matter)
472 | 
473 |   YAML front-matter is your friend. You can keep metadata in markdown files
474 | 
475 |   ```yaml
476 |   title: Serverless Framework Documentation
477 |   description: "Great F'in docs!"
478 |   menuText: Docs
479 |   layout: Doc
480 |   ```
481 | 
482 | 2. [Remark](https://www.npmjs.com/package/remark)
483 | 
484 |   Useful for rendering markdown in HTML/React
485 | 
486 | 3. [Markdown Magic](https://github.com/DavidWells/markdown-magic)
487 | 
488 |   - [Repo](https://github.com/DavidWells/markdown-magic)
489 |   - [Plugins](https://github.com/DavidWells/markdown-magic#plugins)
490 |   - Show automatic doc generation. [Example 1](https://github.com/DavidWells/markdown-magic/blob/master/examples/generate-readme.js#L15-L23)   | [Example 2](https://github.com/serverless/examples/blob/master/generate-readme.js#L71-L87)
491 | 
492 | ---
493 | 
494 | ## Useful utilities
495 | 
496 | 1. [Schedule Posts](https://github.com/DavidWells/static-site-post-scheduler) - Post scheduler for static sites
497 | 
498 |   Show DEMO
499 | 
500 | 2. [Zero friction inline content editing](https://jekyll-anon.surge.sh/gods/2015/02/18/vesta.html)
501 | 
502 |   Show DEMO
503 | 
504 | 3. [Byword](https://bywordapp.com/) & [Typora](https://typora.io/) - Good Editors
505 | 
506 | 4. [Monodraw](https://monodraw.helftone.com/) - Flow charts for days
507 | 
508 | 6. [Kap](https://getkap.co/) - Make gifs
509 | 
510 | 4. [IDE markdown preview](https://atom.io/packages/markdown-preview)
511 | 
512 | 5. Stuck on WordPress? Try [easy-markdown plugin](https://github.com/DavidWells/easy-markdown)
513 | 
514 | ---
515 | 
516 | ## How Serverless uses markdown
517 | 
518 | Serverless.com is comprised of 3 separate repositories
519 | 
520 | - https://github.com/serverless/blog
521 | - https://github.com/serverless/serverless | Shoutout to [Phenomic.io](https://phenomic.io/)
522 | - https://github.com/serverless/site
523 | 
524 | **Why multiple repos?**
525 | 
526 | 1. We wanted documentation about the framework to live in the serverless github repo for easy access
527 | 2. We wanted our blog content to be easily portable to any static site generator separate from the implementation (site)
528 | 3. `prebuild` npm script pulls the content together & processes them for site build
529 | 
530 | A single repo is easier to manage but harder for people to find/edit/PR content.
531 | 
532 | ---
533 | 
534 | ### DEMO
535 | 
536 | - Site structure
537 | - Serverless build process
538 | - [Validation](https://github.com/serverless/blog/blob/master/.travis.yml#L10)
539 | - [Editing Flow](https://serverless.com/framework/docs/providers/aws/cli-reference/deploy/)
540 | - Github optimizations
541 |   - [Link from top of each doc to live link on site](https://github.com/serverless/serverless/blob/master/docs/providers/aws/events/schedule.md)
542 |   - use markdown magic =) to [auto generate tables](https://github.com/serverless/examples) etc
543 |   - [Hide yaml frontmatter from github folks](https://github.com/serverless/serverless/blame/master/docs/providers/aws/events/schedule.md#L1-L7)
544 |   - consider linking everything to site
545 | 
546 | ## Other Markdown Resources
547 | 
548 | - [Extended markdown syntax](https://www.markdownguide.org/extended-syntax/)
549 | - [Markdown snippets](https://github.com/markdown-templates/markdown-snippets)
550 | - [Verb](https://www.npmjs.com/package/verb) - Documentation generator for GitHub projects
551 | - [ACSII docs](http://asciidoctor.org/) - Markdown alternative
552 | - [Markdown parser performance comparison](https://github.com/Expensify/App/issues/3983#issue-942245008)
553 | - [Handy markdown templates](https://github.com/G3root/readme-generator/blob/9219c5ee638f3b8ff429c5b514d4d211661ae136/src/data/project-block-list.ts)
554 | 


--------------------------------------------------------------------------------