Skip to content

Commit bc17b1a

Browse files
michaeltlombardimichaeltlombardi
authored
(AB-4176) Document contributing with codesapces (#10073)
This change adds a new article to the contributor's guide for using a GitHub Codespace for authoring and editing contributions. This article explains how a contributor can setup a codespace and use it when contributing to the PowerShell documentation. It includes a few tips and a list of resources. - Fixes AB#4176
1 parent 32a0143 commit bc17b1a

File tree

5 files changed

+317
-11
lines changed

5 files changed

+317
-11
lines changed

‎.devcontainer/Dockerfile

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
FROM mcr.microsoft.com/devcontainers/base:ubuntu
2-
RUN wget https://github.com/errata-ai/vale/releases/download/v2.22.0/vale_2.22.0_Linux_64-bit.tar.gz && \
3-
tar -xvzf vale_2.22.0_Linux_64-bit.tar.gz -C bin && \
2+
RUN wget https://github.com/errata-ai/vale/releases/download/v2.26.0/vale_2.26.0_Linux_64-bit.tar.gz && \
3+
tar -xvzf vale_2.26.0_Linux_64-bit.tar.gz -C bin && \
44
export PATH=./bin:"$PATH"

‎.devcontainer/devcontainer.json

+18-9
Original file line numberDiff line numberDiff line change
@@ -5,16 +5,21 @@
55
"features": {
66
"ghcr.io/devcontainers/features/git:1": {},
77
"ghcr.io/devcontainers/features/github-cli:1": {},
8-
"ghcr.io/devcontainers/features/powershell:1": {}
8+
"ghcr.io/devcontainers/features/powershell:1": {
9+
"modules": "Documentarian,Documentarian.Vale,Documentarian.MicrosoftDocs,Documentarian.ModuleAuthor"
10+
}
911
},
1012
"customizations": {
1113
"vscode": {
1214
"extensions": [
13-
"darkriszty.markdown-table-prettify",
15+
"chrischinchilla.vale-vscode",
1416
"davidanson.vscode-markdownlint",
15-
"docsmsft.docs-authoring-pack",
17+
"docsmsft.docs-images",
18+
"docsmsft.docs-linting",
19+
"docsmsft.docs-markdown",
20+
"docsmsft.docs-preview",
21+
"docsmsft.docs-yaml",
1622
"eamodio.gitlens",
17-
"errata-ai.vale-server",
1823
"marvhen.reflow-markdown",
1924
"ms-vscode.powershell",
2025
"ms-vscode.wordcount",
@@ -24,10 +29,14 @@
2429
"streetsidesoftware.code-spell-checker",
2530
"tyriar.sort-lines",
2631
"usernamehw.errorlens",
27-
"wmaurer.change-case",
28-
"Acrolinx.vscode-sidebar",
29-
"yzane.markdown-pdf"
30-
]
32+
"wmaurer.change-case"
33+
],
34+
"settings": {
35+
"terminal.integrated.defaultProfile.linux": "pwsh",
36+
"vale.valeCLI.path": "",
37+
"vale.valeCLI.config": ""
38+
}
3139
}
32-
}
40+
},
41+
"postStartCommand": "vale sync"
3342
}

‎.vscode/cspell/psdocs/dictionaries/psdocs.txt

+5
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,9 @@ cnotlike
4949
cnotmatch
5050
codepage
5151
codepages
52+
codespace
53+
codespaces
54+
Codespaces
5255
computername
5356
coreclr
5457
CoreOS
@@ -63,6 +66,8 @@ deserialization
6366
deserialize
6467
deserialized
6568
deserializes
69+
devcontainer
70+
devcontainers
6671
devlang
6772
DHCP
6873
differentiators

‎reference/docs-conceptual/community/contributing/using-github-codespaces.md

+290
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,290 @@
1+
---
2+
description: >-
3+
This article describes the process for contributing to the documentation using GitHub
4+
Codespaces as an authoring environment.
5+
ms.date: 05/10/2023
6+
ms.topic: conceptual
7+
title: Contribute using GitHub Codespaces
8+
---
9+
10+
# Contribute using GitHub Codespaces
11+
12+
GitHub has a feature called [Codespaces][01] that you can use to contribute to the PowerShell
13+
documentation without having to install or configure any software locally. When you use a
14+
codespace, you get the same authoring tools the team uses for writing and editing.
15+
16+
You can use a codespace in your browser, making your contributions in VS Code hosted over the
17+
internet. If you have VS Code installed locally, you can connect to the codespace there too.
18+
19+
## Available tools
20+
21+
When you use a codespace to contribute to the PowerShell documentation, your editor has these tools
22+
already available for you:
23+
24+
- [Markdownlint][02] for checking your Markdown syntax.
25+
- [cSpell][03] for checking your spelling.
26+
- [Vale][04] for checking your prose.
27+
- The [Learn Authoring Pack][05] for inserting platform-specific syntax, previewing your
28+
contribution, and more.
29+
- The [Reflow Markdown][06] extension for wrapping your Markdown as needed, making reading and
30+
editing easier.
31+
- The [Table Formatter][07] extension for making your tables more readable without having to
32+
manually align columns.
33+
- The [change-case][08] extension for converting the casing of your headings and prose.
34+
- The [GitLens][09] extension for reviewing historical file changes.
35+
- The [PowerShell][10] extension for interacting authoring PowerShell examples.
36+
- The [Gremlins tracker for Visual Studio Code][11] for finding problematic characters in your
37+
Markdown.
38+
39+
## Cost
40+
41+
GitHub Codespaces can be used for free up to 120 core-hours per month. With the configuration we
42+
recommend in this article, that means up to 60 hours of free usage per month. The monthly usage is
43+
calculated across all your repositories, not just documentation.
44+
45+
For more information about pricing, see [About billing for GitHub Codespaces][12].
46+
47+
> [!TIP]
48+
> If you're comfortable using containers and Docker, you can get the same experience as using
49+
> GitHub Codespaces in VS Code by using the devcontainer defined for the PowerShell documentation
50+
> repositories. There's no cost associated with using devcontainers. For more information, see
51+
> the [Dev Containers tutorial][13].
52+
53+
## Creating your GitHub Codespace
54+
55+
To create your GitHub Codespace for contributing to PowerShell documentation, follow these steps:
56+
57+
1. Open [https://github.com/codespaces][14] in your browser.
58+
1. Select the "New codespace" button in the top right of the page.
59+
1. In the "Create a new codespace" page, select the "Select a repository" button and type the name
60+
of the repository you want to contribute to, like `MicrosoftDocs/PowerShell-Docs`.
61+
1. Leave all other settings as their default.
62+
1. Select the "Create codespace" button.
63+
64+
After following these steps, GitHub creates a new codespace for that repository and sets it up for
65+
you. When the codespace is ready, the page refreshes and shows the web editor UI for the codespace.
66+
The UI is based on VS Code and works the same way.
67+
68+
## Opening your GitHub Codespace
69+
70+
To open your GitHub Codespace in the browser, follow these steps:
71+
72+
1. Open [https://github.com/codespaces][14] in your browser.
73+
1. The page lists your codespaces. Find the created codespace for the repository you want to
74+
contribute to and select it.
75+
76+
After you select your codespace, GitHub opens it in the same window. From here, you're ready to
77+
contribute.
78+
79+
To open your GitHub Codespace in VS Code, follow the steps in
80+
[Using GitHub Codespaces in Visual Studio Code][15].
81+
82+
## Authoring in your GitHub Codespace
83+
84+
Once you have your GitHub Codespace open in your browser or VS Code, contributing to the
85+
documentation follows the same process.
86+
87+
The rest of this article describes a selection of tasks you can do in your GitHub Codespace while
88+
writing or editing your contribution.
89+
90+
### Extract a reference link
91+
92+
When you want to turn an inline link, like `[some text](destination.md)`, into a reference link like
93+
`[some text][01]`, select the link destination in the editor. Then you can either:
94+
95+
1. Right click on the link destination and select "Refactor..." in the context menu.
96+
1. Press <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd>.
97+
98+
Either action raises the refactoring context menu. Select "Extract to link definition" in the
99+
context menu. This replaces the `(destination.md)` in the link with `[def]`. You can rename the
100+
definition by typing a name in.
101+
102+
For the PowerShell documentation, we use two-digit numerical reference link definitions, like
103+
`[01]` or `[31]`. Only use reference link definitions in about topics and conceptual documentation.
104+
Don't use reference link definitions in cmdlet reference documentation.
105+
106+
### Fix prose style violations
107+
108+
When you review an article in your codespace, Vale automatically checks the article when you first
109+
open it and every time you save it. If Vale finds any style violations, it highlights them in the
110+
document with colored squiggles.
111+
112+
Hover over a violation to see more information about it.
113+
114+
Select the rule's name in the hover information to open a web page that explains the rule. Select
115+
the rule's filename (ending in `.yml`) to open the rule and review its implementation.
116+
117+
If the rule supports a quick fix, you can select "Quick Fix..." in the hover information for the
118+
violation and apply one of the suggested fixes by selecting it from the context menu. You can also
119+
press <kbd>Ctrl</kbd>+<kbd>.</kbd> when your cursor is on a highlighted problem to apply a quick
120+
fix if the rule supports it.
121+
122+
If the rule doesn't support quick fixes, read the rule's message and fix it if you can. If
123+
you're not sure how to fix it, the editors can make a suggestion when reviewing your PR.
124+
125+
### Fix syntax problems
126+
127+
When you review an article in your codespace, Markdownlint automatically checks the article when
128+
you open it and as you type. If Markdownlint finds any syntax problems, it highlights them in the
129+
document with colored squiggles.
130+
131+
Hover over a violation to see more information about it.
132+
133+
Select the rule's ID in the hover information to open a web page that explains the rule.
134+
135+
If the rule supports a quick fix, you can select "Quick Fix..." in the hover information for the
136+
violation and apply one of the suggested fixes by selecting it from the context menu. You can also
137+
press <kbd>Ctrl</kbd>+<kbd>.</kbd> when your cursor is on a highlighted problem to apply a quick
138+
fix if the rule supports it.
139+
140+
If the rule doesn't support quick fixes, read the rule's message and fix it if you can. If
141+
you're not sure how to fix it, the editors can make a suggestion when reviewing your PR.
142+
143+
You can also apply fixes to all syntax violations in an article. To do so, open the command palette
144+
and type `Fix all supported markdownlint violations in the document`. As you type, the command
145+
palette filters the available commands. Select the "Fix all supported markdownlint violations in
146+
the document" command. When you do, Markdownlint updates the document to resolve any violations it
147+
has a quick fix for.
148+
149+
### Format a table
150+
151+
To format a Markdown table, place your cursor in or on the table in your Markdown. Open the Command
152+
Palette and search for the `Table: Format Current` command. When you select that command, it
153+
updates the Markdown for your table to align and pad the table for improved readability.
154+
155+
It converts a table defined like this:
156+
157+
```markdown
158+
| foo | bar | baz |
159+
|:--:|:--|-:|
160+
| a | b | c |
161+
```
162+
163+
Into this:
164+
165+
```markdown
166+
| foo | bar | baz |
167+
| :---: | :--- | ---: |
168+
| a | b | c |
169+
```
170+
171+
### Insert an alert
172+
173+
The documentation uses [alerts][16] to make information more notable to a reader.
174+
175+
To insert an alert, you can, open the Command Palette and search for the `Learn: Alert` command.
176+
When you select that command, it opens a context menu. Select the alert type you want to add. When
177+
you do, the command inserts the alert's Markdown at your cursor in the document.
178+
179+
### Make a heading use sentence casing
180+
181+
To convert a heading's casing, highlight the heading's text except for the leading `#` symbols,
182+
which set the heading level. When you have the text highlighted, open the Command Palette and
183+
search for the `Change case sentence` command. When you select that command, it converts the casing
184+
of the highlighted text.
185+
186+
You can also use the casing commands for any text in the document.
187+
188+
### Open the Command Palette
189+
190+
You can use VS Code's [Command Palette][17] to run many helpful commands.
191+
192+
To open the Command Palette in the UI, select "View" in the top menu bar. Then select "Command
193+
Palette..." in the context menu.
194+
195+
To open the Command Palette with your keyboard, press the key combination for your operating system:
196+
197+
- Windows and Linux: <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>
198+
- macOS: <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>P</kbd>
199+
200+
### Preview your contribution
201+
202+
To preview your contribution, open the Command Palette and search for the `Markdown: Open Preview`
203+
command. When you select that command, VS Code opens a preview of the active document. The
204+
preview's style matches the Learn platform.
205+
206+
> [!NOTE]
207+
> Site-relative and cross-reference links won't work in the preview.
208+
209+
### Reflow your content
210+
211+
To limit the line lengths for a paragraph in a document, place your cursor on the paragraph. Then
212+
open the Command Palette and search for the `Reflow Markdown` command. When you select the command,
213+
it updates the current paragraph's line lengths to the configured length. For our repositories,
214+
that length is 99 characters.
215+
216+
When using this command for block quotes, make sure the paragraph in the block quote you're
217+
reflowing is surrounded by blank lines. Otherwise, the command reflows every paragraph together.
218+
219+
> [!CAUTION]
220+
> Don't use this command when editing about topics. The lines in those documents must not be
221+
> longer than 80 characters. There's currently no way for a repository to configure different line
222+
> lengths by folder or filename, so reflow doesn't work for about topic documents.
223+
224+
### Review all problems in a document
225+
226+
To review all syntax and style rule violations in a document, open the Problems View.
227+
228+
To open the Problems View in the UI, select "View" in the top menu bar. Then select "Problems" in
229+
the context menu.
230+
231+
To open the Problems View with your keyboard, press the key combination for your operating system:
232+
233+
- Windows and Linux: <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd>
234+
- macOS: <kbd>Cmd</kbd>+<kbd>Shift</kbd>+<kbd>M</kbd>
235+
236+
The Problems View displays all errors, warnings, and suggestions for the open document. Select a
237+
problem to scroll to it in the document.
238+
239+
You can filter the problems by type or text matching.
240+
241+
### Updating the ms.date metadata
242+
243+
To update the `ms.date` metadata for an article, open the Command Palette and search for the
244+
`Learn: Update "ms.date" Metadata Value` command. When you select the command, it updates the
245+
metadata to the current date.
246+
247+
## Additional resources
248+
249+
The tasks and commands described in this article don't cover everything you can do with VS Code or
250+
the installed extensions.
251+
252+
For more information on using VS Code, see these articles:
253+
254+
- [Visual Studio Code Tips and Tricks][18]
255+
- [Basic Editing][19]
256+
- [Using Git source control in VS Code][20]
257+
- [Markdown and Visual Studio Code][21]
258+
259+
For more information about the installed extensions, see their documentation:
260+
261+
- [change-case][08]
262+
- [GitLens][09]
263+
- [Gremlins tracker for Visual Studio Code][11]
264+
- [Learn Authoring Pack][05]
265+
- [markdownlint][02]
266+
- [Reflow Markdown][06]
267+
- [Table Formatter][07]
268+
269+
<!-- Reference link definitions -->
270+
[01]: https://github.com/features/codespaces
271+
[02]: https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint
272+
[03]: https://cspell.org/
273+
[04]: https://vale.sh/
274+
[05]: https://marketplace.visualstudio.com/items?itemName=docsmsft.docs-authoring-pack
275+
[06]: https://marketplace.visualstudio.com/items?itemName=marvhen.reflow-markdown
276+
[07]: https://marketplace.visualstudio.com/items?itemName=shuworks.vscode-table-formatter
277+
[08]: https://marketplace.visualstudio.com/items?itemName=wmaurer.change-case
278+
[09]: https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens
279+
[10]: https://marketplace.visualstudio.com/items?itemName=ms-vscode.PowerShell
280+
[11]: https://marketplace.visualstudio.com/items?itemName=nhoizey.gremlins
281+
[12]: https://docs.github.com/en/billing/managing-billing-for-github-codespaces/about-billing-for-github-codespaces
282+
[13]: https://code.visualstudio.com/docs/devcontainers/tutorial
283+
[14]: https://github.com/codespaces
284+
[15]: https://docs.github.com/codespaces/developing-in-codespaces/using-github-codespaces-in-visual-studio-code
285+
[16]: /contribute/markdown-reference#alerts-note-tip-important-caution-warning
286+
[17]: https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette
287+
[18]: https://code.visualstudio.com/docs/getstarted/tips-and-tricks
288+
[19]: https://code.visualstudio.com/docs/editor/codebasics
289+
[20]: https://code.visualstudio.com/docs/sourcecontrol/overview
290+
[21]: https://code.visualstudio.com/docs/languages/markdown

‎reference/docs-conceptual/toc.yml

+2
Original file line numberDiff line numberDiff line change
@@ -498,6 +498,8 @@ items:
498498
href: community/contributing/overview.md
499499
- name: Get started writing docs
500500
href: community/contributing/get-started-writing.md
501+
- name: Contribute using GitHub Codespaces
502+
href: community/contributing/using-github-codespaces.md
501503
- name: Markdown best practices
502504
href: community/contributing/general-markdown.md
503505
- name: PowerShell-Docs style guide

0 commit comments

Comments
 (0)