From 291d087ee5397ed7b8fbc59a6b58ccdfba535f82 Mon Sep 17 00:00:00 2001 From: cool88 Date: Thu, 8 Jun 2017 15:46:11 +0530 Subject: [PATCH 1/2] I think the guideline is missing this imp part --- content/writers-guide.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/content/writers-guide.md b/content/writers-guide.md index 391b9f990712..7f25b9e14bd6 100644 --- a/content/writers-guide.md +++ b/content/writers-guide.md @@ -10,10 +10,11 @@ title: Writer's Guide ## Article Structure -1. Brief introduction - a paragraph or two so you get the basic idea. Tell what you are going to tell. -2. Main content - tell what you promised to tell. -3. Conclusion - tell what you told and recap the main points. -4. References - link to related articles and external resources so people can read and learn more about the topic. +1. Brief introduction - a paragraph or two so you get the basic idea about - the what and why. +2. Structure description for the "Main Content" - the how - how you will tell it in a brief paragraph (e.g. a new plugin or a webpack concept) +3. Main content - tell what you promised to tell. +4. Conclusion - tell what you told and recap the main points. +5. References - link to related articles and external resources so people can read and learn more about the topic. ## Running the Site From 4eb461c5a52a54e9f67af177a438a2c0262afc78 Mon Sep 17 00:00:00 2001 From: Greg Venech Date: Sun, 2 Jul 2017 15:42:17 -0400 Subject: [PATCH 2/2] docs(writers-guide): tweak writers-guide and add section on YAML frontmatter --- content/writers-guide.md | 40 ++++++++++++++++++++++++++++++++++++---- 1 file changed, 36 insertions(+), 4 deletions(-) diff --git a/content/writers-guide.md b/content/writers-guide.md index 7f25b9e14bd6..f2b0130dd6fd 100644 --- a/content/writers-guide.md +++ b/content/writers-guide.md @@ -2,19 +2,49 @@ title: Writer's Guide --- +The following sections contain all you need to know about editing and formatting the content within this site. Make sure to do some research before starting your edits or additions. Sometimes the toughest part is finding where the content should live and determining whether or not it already exists. + + ## Process 1. Check related issue if an article links to one. 2. Hit `edit` and expand on the structure. 3. PR changes. + +## YAML Frontmatter + +Each article contains a small section at the top written in [YAML Frontmatter](): + +``` md +--- +title: My Article +sort: 3 +contributors: + - [github username] +related: + - title: Title of Related Article + url: [url of related article] +--- +``` + +Let's break these down: + +- `title`: The name of the article. +- `sort`: The order of the article within its section. +- `contributors`: A list of GitHub usernames who have contributed to this article. +- `related`: Any related reading or useful examples. + +Note that `related` will generate a __Further Reading__ section at the bottom of the page and `contributors` will yield a __Contributors__ section below it. If you edit an article and would like recognition, please feel free to add your GitHub username to the `contributors` list. + + ## Article Structure -1. Brief introduction - a paragraph or two so you get the basic idea about - the what and why. -2. Structure description for the "Main Content" - the how - how you will tell it in a brief paragraph (e.g. a new plugin or a webpack concept) -3. Main content - tell what you promised to tell. +1. Brief Introduction - a paragraph or two so you get the basic idea about the what and why. +2. Outline Remaining Content – how the content will be presented. +3. Main Content - tell what you promised to tell. 4. Conclusion - tell what you told and recap the main points. -5. References - link to related articles and external resources so people can read and learn more about the topic. + ## Running the Site @@ -24,6 +54,7 @@ title: Writer's Guide The site will update itself as you make changes. + ## Typesetting * webpack should always be written in lower-case letters. Even at the beginning of a sentence. ([source](https://github.com/webpack/media#name)) @@ -32,6 +63,7 @@ The site will update itself as you make changes. * Use "webpack 2" to refer to a specific webpack version (~~"webpack v2"~~) * Use ES5; ES2015, ES2016, … to refer to the ECMAScript standards (~~ES6~~, ~~ES7~~) + ## Formatting ### Code