Skip to content

Commit 5647b14

Browse files
geoffclinegeoffcline
authored
fixup title for SEO, add github edit links, add asciidoc contributor guide (#594)
* fixup title for SEO * init draft * add contributor guide * add github links
1 parent 205bf85 commit 5647b14

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

71 files changed

+525
-85
lines changed

‎.vale.ini‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
StylesPath = vale/styles
22

3-
Packages = RedHat, AsciiDoc, BpgDocs
3+
Packages = RedHat, AsciiDoc
44

55
# Ignore files in dirs starting with `.` to avoid raising errors for `.vale/fixtures/*/testinvalid.adoc` files
66
[[!.]*.adoc]

‎latest/bpg/autoscaling/cluster-autoscaler.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -632,3 +632,6 @@ Marcin Wielgus
632632
* https://github.com/kubernetes/autoscaler/blob/master/cluster-autoscaler/cloudprovider/aws/README.md
633633
* https://github.com/aws/amazon-ec2-instance-selector
634634
* https://github.com/aws/aws-node-termination-handler
635+
636+
637+
📝 https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg/autoscaling/cluster-autoscaler.adoc[Edit this page on GitHub]

‎latest/bpg/autoscaling/index.adoc‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -20,11 +20,9 @@ This guide provides advice about Cluster Autoscaling, including guidance for Kub
2020
[.topiclist]
2121
[[Topic List]]
2222

23+
📝 https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg/autoscaling/index.adoc[Edit this page on GitHub]
24+
2325
include::karpenter.adoc[leveloffset=+1]
2426

2527
include::cluster-autoscaler.adoc[leveloffset=+1]
2628

27-
28-
29-
30-

‎latest/bpg/autoscaling/karpenter.adoc‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -120,7 +120,7 @@ https://karpenter.sh/docs/concepts/nodeclasses/[NodeClasses].
120120
=== Exclude instance types that do not fit your workload
121121

122122
Consider excluding specific instances types with the
123-
http://node.kubernetes.io/instance-type[node.kubernetes.io/instance-type]
123+
`node.kubernetes.io/instance-type`
124124
key if they are not required by workloads running in your cluster.
125125

126126
The following example shows how to avoid provisioning large Graviton
@@ -285,7 +285,6 @@ kind: Deployment
285285
metadata:
286286
name: inflate-gpu
287287
spec:
288-
...
289288
spec:
290289
tolerations:
291290
- key: "nvidia.com/gpu"
@@ -351,7 +350,6 @@ metadata:
351350
name: workload-my-team
352351
spec:
353352
replicas: 200
354-
...
355353
spec:
356354
affinity:
357355
nodeAffinity:
@@ -620,3 +618,6 @@ for your workload(s).
620618
Karpenter]
621619
* https://community.aws/tutorials/run-kubernetes-clusters-for-less-with-amazon-ec2-spot-and-karpenter#step-6-optional-simulate-spot-interruption[Tutorial:
622620
Run Kubernetes Clusters for Less with Amazon EC2 Spot and Karpenter]
621+
622+
623+
📝 https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg/autoscaling/karpenter.adoc[Edit this page on GitHub]

‎latest/bpg/book.adoc‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@
2424

2525
[abstract]
2626
--
27-
Insert abstract text
27+
Learn best practices for operating EKS clusters.
2828
--
2929
:sectnums:
3030

@@ -46,4 +46,6 @@ include::cost/cost_optimization_index.adoc[leveloffset=+1]
4646

4747
include::windows/index.adoc[leveloffset=+1]
4848

49+
include::contribute.adoc[leveloffset=+1]
50+
4951

‎latest/bpg/contribute.adoc‎

Lines changed: 300 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,300 @@
1+
//!!NODE_ROOT <chapter>
2+
[."topic"]
3+
[[contribute,contribute.title]]
4+
= Contribute to this guide
5+
:info_doctype: chapter
6+
:info_titleabbrev: Contribute
7+
8+
9+
Anyone can contribute to the best practices guide. The EKS Best Practices Guide is written in the AsciiDoc format on GitHub.
10+
11+
== Summary for existing contributors
12+
13+
* Open the https://github.com/aws/aws-eks-best-practices/blob/master/bpg-docs.code-workspace[`bpg-docs.code-workspace`] with VS Code to automatically install the AsciiDoc extension.
14+
** Learn more about the https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[AsciiDoc Extension] on the Visual Studio Marketplace.
15+
* The source files for the AWS Docs website are stored in https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg[`latest/bpg`]
16+
* The syntax is highly similar to markdown.
17+
** Review the https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[Syntax Reference] in the AsciiDoctor docs.
18+
* The docs platform only deploys `latest/bpg/images`. Each of the guide sections has a symbolic link back to this directory. For example, `latest/bpg/networking/images` points to `latest/bpg/images`.
19+
20+
== Setup a local editing environment
21+
22+
If you plan to edit the guide frequently, setup a local editing environment.
23+
24+
=== Fork and clone the repo
25+
26+
You need to be familiar with `git`, `github`, and text editors. For information on getting started with `git` and `github`, see https://docs.github.com/en/get-started/onboarding/getting-started-with-your-github-account[Getting started with your GitHub account] in the GitHub docs.
27+
28+
. View the https://github.com/aws/aws-eks-best-practices[EKS Best Practices Guide on GitHub].
29+
. Create a fork of the project repo. Learn how to https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#forking-a-repository[fork a repository] in the GitHub docs.
30+
. Clone your fork of the project repo. Learn how to https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo#cloning-your-forked-repository[clone your forked repository].
31+
32+
=== Open the VS Code Workspace
33+
34+
AWS recommends using Visual Studio Code from Microsoft to edit the guide. For more information about VS Code, see https://code.visualstudio.com/download[Download Visual Studio Code] and https://code.visualstudio.com/docs/getstarted/getting-started[Get started with Visual Studio Code] in the Visual Studio Code Documentation.
35+
36+
. Open VS Code.
37+
. Open the `bpg-docs.code-workspace` file from the cloned repo.
38+
. If this is your first time opening this workspace, accept the prompt to install the AsciiDoc extension. This extension checks the syntax of AsciiDoc files and generates a live preview.
39+
. Browse to the `latest/bpg` directory. This directory holds the source files that deploy to the AWS documentation site. The source files are organized by guide section, such as "security" or "networking".
40+
41+
=== Edit a file
42+
43+
. Open a file in the editor.
44+
** View the AsciiDoc Syntax to learn how to create headings, links, and lists.
45+
** You can use Markdown syntax to format text, create lists, and headings. You cannot use Markdown syntax to create links.
46+
. Open a live preview of the page.
47+
** First, press `ctrl-k` or `cmd-k` (depending on keyboard). Second, press `v`. This opens a preview in split view.
48+
49+
AWS suggests using feature branches to organize your changes. Learn how to create branches with git.
50+
51+
=== Submit a Pull Request
52+
53+
You can create a pull request from the GitHub website or the GitHub cli.
54+
55+
Learn how to https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork[create a pull request from a fork] by using the GitHub Website.
56+
57+
Learn how to https://cli.github.com/manual/gh_pr_create[create a pull request] by using the GitHub cli.
58+
59+
// == Edit the guide online
60+
61+
// Editing the guide online is a great way to make a small change to a single page.
62+
63+
== View and set the ID for a page
64+
65+
This page explains how to view and set page ID.
66+
67+
The page ID is a unique string that identifies each page on the documentation site. You can view the page ID in the address bar of your browser when you're on a specific page. The page ID is used for the URL, the filename, and to create cross reference links.
68+
69+
For example, if you're viewing this page, the URL in your browser's address bar will look similar to:
70+
71+
```
72+
https://docs.aws.amazon.com/view-set-page-id.html
73+
```
74+
75+
The last part of the URL (`view-set-page-id`) is the page ID.
76+
77+
=== Set the page ID
78+
79+
When creating a new page, you need to set the page ID in the source file. The page ID should be a concise, hyphenated string that describes the page content.
80+
81+
. Open the source file for your new page in a text editor.
82+
. At the top of the file, add the following line. It should be above the first heading.
83+
+
84+
```asciidoc
85+
[#my-new-page]
86+
```
87+
+
88+
Replace `my-new-page` with the desired page ID for your new page.
89+
. Save the file.
90+
91+
NOTE: Page IDs must be unique across the entire documentation site. If you try to use an existing page ID, you'll get a build error.
92+
93+
94+
== Create a new page
95+
96+
Learn how create a new page and update the guide table of contents.
97+
98+
=== Create page metadata
99+
100+
. Determine the page title, and page short title. The page short title is optional, but recommended if the page title is more than a few words.
101+
. Determine the ID of the page. This must be unique within the EKS Best Practices Guide. The convention is to use all lowercase, and separate words with `-`.
102+
. Create a new asciidoc file, in a folder if needed, and add the following text to the file:
103+
+
104+
====
105+
+[."topic"]+
106+
+[#<page-id>]+
107+
+= <page-title>+
108+
+:info_titleabbrev: <page-short-title>+
109+
====
110+
+
111+
For example,
112+
+
113+
====
114+
+[."topic"]+
115+
+[#scalability]+
116+
+= EKS Scalability best practices+
117+
+:info_titleabbrev: Scalability+
118+
====
119+
120+
121+
=== Add to table of contents
122+
123+
. Open the file for the parent page in the table of contents. For new top level guide sections, the parent file is `book.adoc`.
124+
. At the bottom of the parent file, update and insert the following directive:
125+
+
126+
====
127+
+include::<new-filename>[leveloffset=+1]+
128+
====
129+
+
130+
For Example,
131+
+
132+
====
133+
+include::dataplane.adoc[leveloffset=+1]+
134+
====
135+
136+
== Insert an image
137+
138+
. Find the image prefix for the page you are editing. Review the `:imagesdir:` property in the heading of the file. For examples, ``:imagesdir: images/reliability/`
139+
. Place your image in this path, such as `latest/bpg/images/reliability`
140+
. Determine appropriate alt-text for you image. Write a short high-level description of the image. For example, "diagram of VPC with three availability zones" is appropriate alt-text.
141+
. Update the following example with the alt-text and image filename. Insert at the desired location.
142+
+
143+
====
144+
+image::<image-filename>[<image-alt-text>]+
145+
====
146+
+
147+
For example,
148+
+
149+
====
150+
+image::eks-data-plane-connectivity.jpeg[Network diagram]+
151+
====
152+
153+
== Check style with Vale
154+
155+
. https://vale.sh/docs/vale-cli/installation/[Install the Vale CLI.]
156+
. Run `vale sync`
157+
. Install the https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode[Vale Extension] from the Visual Studio Marketplace.
158+
. Restart VS Code, and open an AsciiDoc file
159+
. VS Code underlines problematic text. Learn how to work with https://code.visualstudio.com/docs/editor/editingevolved#_errors-warnings[Errors and Warnings] in the VS Code docs.
160+
161+
== Build a local preview
162+
163+
. Install the `asciidoctor` tool using `brew` on Linux or MacOS
164+
** Learn how to https://docs.asciidoctor.org/asciidoctor/latest/install/[install asciidoctor cli] in the AsciiDoctor docs.
165+
** Learn how https://brew.sh/index.html[install the brew package manager].
166+
. Open a terminal, and navigate to `latest/bpg/`
167+
. Run `asciidoctor book.adoc`
168+
** Review any syntax warnings and errors
169+
. Open the `book.html` output file.
170+
** On MacOS, you can run `open book.html` to open the preview in your default browser.
171+
172+
== AsciiDoc Cheat Sheet
173+
174+
=== Basic Formatting
175+
176+
[source,asciidoc]
177+
----
178+
*bold text*
179+
_italic text_
180+
`monospace text`
181+
----
182+
183+
=== Headers
184+
185+
[source,asciidoc]
186+
----
187+
= Document Title (Header 1)
188+
== Header 2
189+
=== Header 3
190+
==== Header 4
191+
===== Header 5
192+
====== Header 6
193+
----
194+
195+
=== Lists
196+
197+
Unordered Lists:
198+
199+
[source,asciidoc]
200+
----
201+
- Item 1
202+
- Item 2
203+
-- Subitem 2.1
204+
-- Subitem 2.2
205+
- Item 3
206+
----
207+
208+
Ordered Lists:
209+
210+
[source,asciidoc]
211+
----
212+
. First item
213+
. Second item
214+
.. Subitem 2.1
215+
.. Subitem 2.2
216+
. Third item
217+
----
218+
219+
=== Links
220+
221+
[source,asciidoc]
222+
----
223+
External link: https://example.com[Link text]
224+
Internal link: <<page-id>>
225+
Internal link: xref:page-id[Link text]
226+
----
227+
228+
=== Images
229+
230+
[source,asciidoc]
231+
----
232+
image::image-file.jpg[Alt text]
233+
----
234+
235+
=== Code Blocks
236+
237+
[source,asciidoc]
238+
----
239+
[source,python]
240+
----
241+
def hello_world():
242+
print("Hello, World!")
243+
----
244+
----
245+
246+
=== Tables
247+
248+
https://docs.asciidoctor.org/asciidoc/latest/tables/build-a-basic-table/[Learn how to build a basic table.]
249+
250+
[source,asciidoc]
251+
----
252+
[cols="1,1"]
253+
|===
254+
|Cell in column 1, row 1
255+
|Cell in column 2, row 1
256+
257+
|Cell in column 1, row 2
258+
|Cell in column 2, row 2
259+
260+
|Cell in column 1, row 3
261+
|Cell in column 2, row 3
262+
|===
263+
----
264+
265+
=== Admonitions
266+
267+
[source,asciidoc]
268+
----
269+
NOTE: This is a note admonition.
270+
271+
WARNING: This is a warning admonition.
272+
273+
TIP: This is a tip admonition.
274+
275+
IMPORTANT: This is an important admonition.
276+
277+
CAUTION: This is a caution admonition.
278+
----
279+
280+
Preview:
281+
282+
NOTE: This is a note admonition.
283+
284+
285+
=== Includes
286+
287+
[source,asciidoc]
288+
----
289+
include::filename.adoc[]
290+
----
291+
292+
293+
294+
295+
296+
297+
298+
299+
300+
📝 https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg/contribute.adoc[Edit this page on GitHub]

‎latest/bpg/cost/awareness.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -223,3 +223,6 @@ Refer to the following resources to learn more about best practices for cost opt
223223
* https://kubecost.com/[Kubecost]
224224
* https://github.com/hjacobs/kube-ops-view[Kube Opsview]
225225
* https://github.com/rchakode/kube-opex-analytics[Kubernetes Opex Analytics]
226+
227+
228+
📝 https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg/cost/awareness.adoc[Edit this page on GitHub]

‎latest/bpg/cost/cfm_framework.adoc‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -62,3 +62,6 @@ Securing executive sponsorship for these types of activities is crucial for inte
6262
* https://aws.amazon.com/aws-cost-management/[AWS Cloud Economics, Cloud Financial Management]
6363

6464

65+
66+
67+
📝 https://github.com/aws/aws-eks-best-practices/tree/master/latest/bpg/cost/cfm_framework.adoc[Edit this page on GitHub]

0 commit comments

Comments
 (0)