diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 15978a4322b25..2b3caa87da75e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -30,18 +30,6 @@ jobs: - name: Run Check run: pnpm run check - tsc: - name: Check for type issues with tsc - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v3 - - - name: Install Tools & Dependencies - uses: ./.github/actions/install - - - name: Run Check - run: pnpm run tsc eslint: name: Check for code issues with ESLint runs-on: ubuntu-latest diff --git a/.gitpod.yml b/.gitpod.yml index 41467bd6c5ac1..c38198e94576e 100644 --- a/.gitpod.yml +++ b/.gitpod.yml @@ -2,5 +2,5 @@ tasks: - init: pnpm install command: pnpm run dev ports: - - port: 3000 + - port: 4321 onOpen: open-browser diff --git a/astro.config.ts b/astro.config.ts index c524bfe6a8e11..b474e51442c72 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -29,6 +29,8 @@ export default defineConfig({ astroDocsExpressiveCode(), mdx(), ], + scopedStyleStrategy: 'where', + compressHTML: false, markdown: { // Override with our own config smartypants: false, diff --git a/contributor-guides/writing-and-style-guide.md b/contributor-guides/writing-and-style-guide.md index 4a57d8a22841a..a80b3f930b8ff 100644 --- a/contributor-guides/writing-and-style-guide.md +++ b/contributor-guides/writing-and-style-guide.md @@ -14,7 +14,7 @@ All readers can benefit from clear, straightforward writing, but this can be par - have cognitive, learning or attention difficulties. - come from a non-traditional development background. -We aim for **clear** and **helpful** documentation that serves the reader above all else! +We aim for **clear** and **helpful** documentation that serves the reader above all else! Usually this means choosing: @@ -59,7 +59,7 @@ Whenever possible, give the reader a direct instruction: e.g. Type the command... -Do not use _"Let's..."_ or _"Next, we will..."_. You are not sitting there with your reader! (This also means you will never need the words _we_, _us_, and _our_. If you see them, rephrase!) +Do not use *"Let's..."* or *"Next, we will..."*. You are not sitting there with your reader! (This also means you will never need the words *we*, *us*, and *our*. If you see them, rephrase!) If you must address the reader, it is OK to use "you" and "your". Especially for emphasis in very important steps where something could go wrong: @@ -85,12 +85,11 @@ Here is an example edit we made to one of our own recipes to illustrate the diff > 1. > 2. ... - ### Opinionated Instructions -Sometimes you will need to give an instruction where the reader has options. You want to illustrate the example with the specific choice you made, but you also want to make it clear that other decisions are acceptable. +Sometimes you will need to give an instruction where the reader has options. You want to illustrate the example with the specific choice you made, but you also want to make it clear that other decisions are acceptable. -In this case, try to separate the instruction from the opinion. First, give the action to take with a more general description. Then state the opinionated choice that your example uses. Your reader will be able to first process what you are doing and then will see the choice you have made. They can still follow your instruction, making a choice that works for their own project. +In this case, try to separate the instruction from the opinion. First, give the action to take with a more general description. Then state the opinionated choice that your example uses. Your reader will be able to first process what you are doing and then will see the choice you have made. They can still follow your instruction, making a choice that works for their own project. This can be easier to follow (and perhaps more reassuring!) than a statement that gives multiple options. This is also usually easier to write since you do not have to remind the reader that this file is from *your* example, and may not appear in their project. @@ -105,7 +104,6 @@ This can be easier to follow (and perhaps more reassuring!) than a statement tha ## Custom Components @@ -161,7 +159,7 @@ By default, the badge uses a muted colour scheme to blend in. It also has an acc ### Since Component -As features are added to Astro, it can be helpful to document _when_ they were added. This allows users to easily see if the version of Astro (or other packages) they are running supports a specific feature as described in the docs. +As features are added to Astro, it can be helpful to document *when* they were added. This allows users to easily see if the version of Astro (or other packages) they are running supports a specific feature as described in the docs. You can use the `` component to display this information in a standardized way. @@ -277,9 +275,10 @@ Inside `MyCustomTabs.jsx`, import the Tabs component and create one `` com --- import Tabs from './Tabs'; --- - + ``` + To create your custom tab component, follow the pattern below using a `` with a named slot for each tab and panel to be created. Note that you must define your tab names here (e.g. Preact, React, Solid, Svelte, Vue), but the content for each panel will be written when your custom component is imported and used in a Markdown page, as in the previous `` example. ```jsx @@ -287,18 +286,18 @@ To create your custom tab component, follow the pattern below using a ` - Preact - React - Solid - Svelte - Vue - - - - - - + + Preact + React + Solid + Svelte + Vue + + + + + + ``` @@ -318,7 +317,7 @@ import RecipeLinks from "~/components/RecipeLinks.astro"; ## Lists vs. Headings -Both lists and headings are used in our docs for readability. We will often start by using `
    ` to list related items. +Both lists and headings are used in our docs for readability. We will often start by using `
      ` to list related items. But, when individual line items become large, span multiple paragraphs, or contain too many `` terms affecting readability, then we will change to section headings. @@ -339,33 +338,36 @@ Do use headings to break up text into organized sections! Many readers prefer to ## Examples (e.g. examples) Current practice is to use the words "for example" in full within the text of a sentence, but (e.g. Netlify, Vercel) inside a parenthetical so as to not take the reader out of the flow the sentence. - -> For example, when passing props . . . -> If you store your Astro project in an online Git provider (e.g. GitHub, GitLab), you can . . . +> For example, when passing props . . . + +> If you store your Astro project in an online Git provider (e.g. GitHub, GitLab), you can . . . ## Code Samples -We take great pride in our code samples, but they require a little extra work to write! +We take great pride in our code samples, but they require a little extra work to write! Don't worry! We'll help you out in a PR if your code authoring needs some adjustment before merging. But, you can make use of all our features below and preview them locally to make sure your code looks the way you want. If you are **editing existing code samples**, then please make sure to preview your updated code sample! Update any necessary syntax such as line highlighting or title (file name). -If you are **adding new code samples**, you have the option of adding a file name (usually recommended!) to be displayed as a title. You can also highlight individual words, phrases, or entire lines in regular or "diff" (red/green) style. +If you are **adding new code samples**, you have the option of adding a file name (usually recommended!) to be displayed as a title. You can also highlight individual words, phrases, or entire lines in regular or "diff" (red/green) style. **All extra code styling is written on the opening line of the code block, immediately after the language.** Here are two examples of what our code snippets look like written in Markdown, just so you can see what it looks like in action. Syntax explanations follow. -#### Example 1 +#### Example 1 + - Use the file name as a title - highlight rows 9 and 10 + ``````markdown ```astro title="src/pages/nested-components.astro" {9-10} `````` -#### Example 2 +#### Example 2 + - use the file name as a title (alt method) - apply "+ diff" styling (green backround) to any occurrence of `