From 0e327ce9a083f1bbd7868a1aca06105f08e06861 Mon Sep 17 00:00:00 2001 From: Misty Linville Date: Thu, 12 Jul 2018 15:01:26 -0700 Subject: [PATCH] Add Atom snippets file (#9158) * Add Atom snippets file * Add more snippets, rename file, address feedback --- config.toml | 2 +- .../en/docs/doc-contributor-tools/README.md | 2 + .../doc-contributor-tools/snippets/README.md | 51 ++++ .../snippets/atom-snippets.cson | 226 ++++++++++++++++++ 4 files changed, 280 insertions(+), 1 deletion(-) create mode 100644 content/en/docs/doc-contributor-tools/README.md create mode 100644 content/en/docs/doc-contributor-tools/snippets/README.md create mode 100644 content/en/docs/doc-contributor-tools/snippets/atom-snippets.cson diff --git a/config.toml b/config.toml index 7390205f49..79cb166760 100644 --- a/config.toml +++ b/config.toml @@ -7,7 +7,7 @@ enableRobotsTXT = true disableKinds = ["taxonomy", "taxonomyTerm"] -ignoreFiles = [ "^OWNERS$", "README.md", "^node_modules$" ] +ignoreFiles = [ "^OWNERS$", "README.md", "^node_modules$", "content/en/docs/doc-contributor-tools" ] contentDir = "content/en" diff --git a/content/en/docs/doc-contributor-tools/README.md b/content/en/docs/doc-contributor-tools/README.md new file mode 100644 index 0000000000..b493e67bd3 --- /dev/null +++ b/content/en/docs/doc-contributor-tools/README.md @@ -0,0 +1,2 @@ +Tools for Kubernetes docs contributors. View `README.md` files in +subdirectories for more info. \ No newline at end of file diff --git a/content/en/docs/doc-contributor-tools/snippets/README.md b/content/en/docs/doc-contributor-tools/snippets/README.md new file mode 100644 index 0000000000..fac2332f37 --- /dev/null +++ b/content/en/docs/doc-contributor-tools/snippets/README.md @@ -0,0 +1,51 @@ +# Snippets for Atom + +Snippets are bits of text that get inserted into your editor, to save typing and +reduce syntax errors. The snippets provided in `atom-snippets.cson` are scoped to +only work on Markdown files within Atom. + +## Installation + +Copy the contents of the `atom-snippets.cson` file into your existing +`~/.atom/snippets.cson`. **Do not replace your existing file.** + +You do not need to restart Atom. + +## Usage + +Have a look through `atom-snippets.cson` and note the titles and `prefix` values +of the snippets. + +You can trigger a given snippet in one of two ways: + +- By typing the snippet's `prefix` and pressing the `` key +- By searching for the snippet's title in **Packages / Snippets / Available** + +For example, open a Markdown file and type `anote` and press ``. A blank +note is added, with the correct Hugo shortcodes. + +A snippet can insert a single line or multiple lines of text. Some snippets +have placeholder values. To get to the next placeholder, press `` again. + +Some of the snippets only insert partially-formed Markdown or Hugo syntax. +For instance, `coverview` inserts the start of a concept overview tag, while +`cclose` inserts a close-capture tag. This is because every type of capture +needs a capture-close tab. + +## Creating new topics using snippets + +To create a new concept, task, or tutorial from a blank file, use one of the +following: + +- `newconcept` +- `newtask` +- `newtutorial` + +Placeholder text is included. + +## Submitting new snippets + +1. Develop the snippet locally and verify that it works as expected. +2. Copy the template's code into the `atom-snippets.cson` file on Github. Raise a + pull request, and ask for review from another Atom user in #sig-docs on + Kubernetes Slack. \ No newline at end of file diff --git a/content/en/docs/doc-contributor-tools/snippets/atom-snippets.cson b/content/en/docs/doc-contributor-tools/snippets/atom-snippets.cson new file mode 100644 index 0000000000..0f7b78f030 --- /dev/null +++ b/content/en/docs/doc-contributor-tools/snippets/atom-snippets.cson @@ -0,0 +1,226 @@ +# Your snippets +# +# Atom snippets allow you to enter a simple prefix in the editor and hit tab to +# expand the prefix into a larger code block with templated values. +# +# You can create a new snippet in this file by typing "snip" and then hitting +# tab. +# +# An example CoffeeScript snippet to expand log to console.log: +# +# '.source.coffee': +# 'Console log': +# 'prefix': 'log' +# 'body': 'console.log $1' +# +# Each scope (e.g. '.source.coffee' above) can only be declared once. +# +# This file uses CoffeeScript Object Notation (CSON). +# If you are unfamiliar with CSON, you can read more about it in the +# Atom Flight Manual: +# http://flight-manual.atom.io/using-atom/sections/basic-customization/#_cson + +'.source.gfm': + + # Capture variables for concept template + # For full concept template see 'newconcept' below + 'Insert concept template': + 'prefix': 'ctemplate' + 'body': 'content_template: templates/concept' + 'Insert concept overview': + 'prefix': 'coverview' + 'body': '{{% capture overview %}}' + 'Insert concept body': + 'prefix': 'cbody' + 'body': '{{% capture body %}}' + 'Insert concept whatsnext': + 'prefix': 'cnext' + 'body': '{{% capture whatsnext %}}' + + + # Capture variables for task template + # For full task template see 'newtask' below + 'Insert task template': + 'prefix': 'ttemplate' + 'body': 'content_template: templates/task' + 'Insert task overview': + 'prefix': 'toverview' + 'body': '{{% capture overview %}}' + 'Insert task prerequisites': + 'prefix': 'tprereq' + 'body': """ + {{% capture prerequisites %}} + + {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + + {{% /capture %}} + """ + 'Insert task steps': + 'prefix': 'tsteps' + 'body': '{{% capture steps %}}' + 'Insert task discussion': + 'prefix': 'tdiscuss' + 'body': '{{% capture discussion %}}' + + + # Capture variables for tutorial template + # For full tutorial template see 'newtutorial' below + 'Insert tutorial template': + 'prefix': 'tutemplate' + 'body': 'content_template: templates/tutorial' + 'Insert tutorial overview': + 'prefix': 'tuoverview' + 'body': '{{% capture overview %}}' + 'Insert tutorial prerequisites': + 'prefix': 'tuprereq' + 'body': '{{% capture prerequisites %}}' + 'Insert tutorial objectives': + 'prefix': 'tuobjectives' + 'body': '{{% capture objectives %}}' + 'Insert tutorial lesson content': + 'prefix': 'tulesson' + 'body': '{{% capture lessoncontent %}}' + 'Insert tutorial whatsnext': + 'prefix': 'tunext' + 'body': '{{% capture whatsnext %}}' + 'Close capture': + 'prefix': 'ccapture' + 'body': '{{% /capture %}}' + 'Insert note': + 'prefix': 'anote' + 'body': """ + {{< note >}} + **Note**: $1 + {{< /note >}} + """ + + # Admonitions + 'Insert caution': + 'prefix': 'acaution' + 'body': """ + {{< caution >}} + **Caution**: $1 + {{< /caution >}} + """ + 'Insert warning': + 'prefix': 'awarning' + 'body': """ + {{< warning >}} + **Warning**: $1 + {{< /warning >}} + """ + + # Misc one-liners + 'Insert TOC': + 'prefix': 'toc' + 'body': '{{< toc >}}' + 'Insert code from file': + 'prefix': 'codefile' + 'body': '{{< code file="$1" >}}' + 'Insert feature state': + 'prefix': 'fstate' + 'body': '{{< feature-state for_k8s_version="$1" state="$2" >}}' + 'Insert figure': + 'prefix': 'fig' + 'body': '{{< figure src="$1" title="$2" alt="$3" caption="$4" >}}' + 'Insert Youtube link': + 'prefix': 'yt' + 'body': '{{< youtube $1 >}}' + + + # Full concept template + 'Create new concept': + 'prefix': 'newconcept' + 'body': """ + --- + reviewers: + - ${1:"github-id-or-group"} + title: ${2:"topic-title"} + content_template: templates/concept + --- + {{% capture overview %}} + ${3:"overview-content"} + {{% /capture %}} + + {{< toc >}} + + {{% capture body %}} + ${4:"h2-heading-per-subtopic"} + {{% /capture %}} + + {{% capture whatsnext %}} + ${5:"next-steps-or-delete"} + {{% /capture %}} + """ + + + # Full task template + 'Create new task': + 'prefix': 'newtask' + 'body': """ + --- + reviewers: + - ${1:"github-id-or-group"} + title: ${2:"topic-title"} + content_template: templates/task + --- + {{% capture overview %}} + ${3:"overview-content"} + {{% /capture %}} + + {{< toc >}} + + {{% capture prerequisites %}} + + {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + + ${4:"additional-prereqs-or-delete"} + + {{% /capture %}} + + {{% capture steps %}} + ${5:"h2-heading-per-step"} + {{% /capture %}} + + {{% capture discussion %}} + ${6:"task-discussion-or-delete"} + {{% /capture %}} + """ + + # Full tutorial template + 'Create new tutorial': + 'prefix': 'newtutorial' + 'body': """ + --- + reviewers: + - ${1:"github-id-or-group"} + title: ${2:"topic-title"} + content_template: templates/tutorial + --- + {{% capture overview %}} + ${3:"overview-content"} + {{% /capture %}} + + {{< toc >}} + + {{% capture prerequisites %}} + + {{< include "task-tutorial-prereqs.md" >}} {{< version-check >}} + + ${4:"additional-prereqs-or-delete"} + + {{% /capture %}} + + {{% capture objectives %}} + ${5:"tutorial-objectives"} + {{% /capture %}} + + {{% capture lessoncontent %}} + ${6:"lesson-content"} + {{% /capture %}} + + {{% capture whatsnext %}} + ${7:"next-steps-or-delete"} + {{% /capture %}} + """ + \ No newline at end of file