Skip to content

Commit

Permalink
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' into fix-pnpx
Browse files Browse the repository at this point in the history
sarah11918 authored Mar 30, 2023
2 parents 6dcf4f1 + ab7482a commit b7b4142
Showing 176 changed files with 6,420 additions and 1,241 deletions.
31 changes: 31 additions & 0 deletions .github/workflows/discord-i18n-ping.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
name: Translation Tuesday

on:
schedule:
- cron: '0 10 * * TUE'
workflow_dispatch:

jobs:
translation:
name: translation_tuesday
if: ${{ github.repository_owner == 'withastro' }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v3
with:
fetch-depth: 0

- name: Install Tools & Dependencies
uses: ./.github/actions/install

- id: message
name: Format Discord message
run: pnpm tsm --require=./scripts/lib/filter-warnings.cjs ./scripts/tuesday-bot.ts

- name: Send a Discord notification
env:
DISCORD_WEBHOOK: ${{ secrets.DISCORD_WEBHOOK_I18N }}
uses: Ilshidur/action-discord@0.3.2
with:
args: "${{ steps.message.outputs.DISCORD_MESSAGE }}"
12 changes: 12 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -16,6 +16,14 @@ This document is an active work in progress! But, we hope you'll find some usefu

## Types of Contributions

There are lots of ways to contribute to the Astro Docs website!

The Astro Docs website is ... an Astro website! Maintaining it requires not only written content but also maintaining Astro code and addressing a11y, CSS, UI, and UX concerns. We also make our documentation available in several languages, so we need help translating the entire site.

You can also make a huge contribution by getting involved by leaving review comments on [PRs](https://github.com/withastro/docs/pulls), adding ideas in existing GitHub [Issues](https://github.com/withastro/docs/issues) and [Discussions](https://github.com/withastro/docs/discussions) and participating in our "Pinned" issue maintenance tasks!

Every PR, especially translation PRs, needs reviewers! Reviewing PRs and leaving comments, suggestions, or an approving "LGTM!" ("Looks Good To Me!") is a great way to get started on Team Docs, and to learn more about Astro.

We encourage you to:

- **File an Issue** to let us know of outdated, confusing, or incorrect documentation. You can also let us know of any problems you encounter on the site itself.
@@ -24,6 +32,10 @@ We encourage you to:

- **Make a PR directly** for very obvious documentation fixes like typos or broken links.

- **Look at our Existing Issues** (especially those labelled [`help wanted`](https://github.com/withastro/docs/issues?q=is:open+is:issue+label:%22help+wanted%22) and [`good first issue`](https://github.com/withastro/docs/issues?q=is:open+is:issue+label:%22good+first+issue%22)) for contributions we are actively seeking.

- **Review Existing PRs** (especially translations!) to help us get our fixes implemented live on the website sooner.

We provide new content and rework existing content _in response to GitHub Issues and Discussions_.

Submitting an Issue is usually the first step to making a change. After an Issue has been considered by the community, we often reach out to community members to encourage them to submit PRs based on existing Issues.
87 changes: 50 additions & 37 deletions RECIPES.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,57 @@
# Contributing to Recipes

Our "Recipes" section in the sidebar highlights step-by-step how-to guides for accomplishing a specific task in Astro. These include established landing pages for deployment, CMS, and migration guide, as well as a [dedicated section](https://docs.astro.build/en/recipes/) for a wider range of tasks you can accomplish with Astro.
Our "Recipes" section in the sidebar highlights **step-by-step how-to guides** for **accomplishing a specific task** in Astro. These include established landing pages for deployment, CMS, and migration guide, as well as a [dedicated section](https://docs.astro.build/en/recipes/) for a wider range of tasks you can accomplish with Astro.

Astro docs welcomes recipe contributions that:

- Edit an [existing recipe](existing-recipes) with corrected content or [new resource links](#add-new-links), by PRing the existing file in the docs repo.
- Add a new [community recipe](#community-recipes) by PRing a link to the ["More Recipes" page](#more-recipes-page): `src/content/docs/guides/recipes.mdx`.
- [Add a new CMS, Deploy or Migration recipe](#cms-deploy-and-migrate) to these existing categories.
- Add a new [official recipe](#official-recipes), by PRing a new page (`.mdx` file) to the `src/content/docs/recipes/` folder.


## Edit Existing Recipes

These have been written by Team Docs and we actively maintain this content. We welcome corrections, updates or more resource links to any of these pages! This content is intended to be kept accurate and up to date. You are welcome to PR a quick fix or resource, or to make an Issue on GitHub to let us know of larger content changes that may be necessary.

You can use the "Edit This Page" link in the right sidebar to make a change on GitHub directly and submit a pull request, or see the [Contributing Guide](https://github.com/withastro/docs/blob/main/CONTRIBUTING.md#making-prs-pull-requests) for other ways to edit the Docs site.

## Community Recipes

Community Recipes are for external links that fit the definition of a recipe: short, focused how-to guides. This lets us include community resources without requiring long-term maintenance. They are listed on our [More Recipes](#more-recipes-page) page in docs.

You can share a published recipe in our “Community Recipes” section. This includes posts on a personal or company blog, or on your preferred blogging platform like [DEV.to](https://dev.to/). This follows the IndieWeb principle of “Publish (on your) Own Site, Syndicate Elsewhere” (often abbreviated to [POSSE](https://indieweb.org/POSSE)).

After you publish your article, [open a PR adding a link to this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/recipes.mdx).

The link should be of the form `[Post or article title](full URL)` and it should be added to the bottom of the list of existing community recipes. Use the existing entries above it as a guide, and if any changes are necessary, we can make them while reviewing the PR.

Please note that all community recipe PRs will be reviewed to make sure they fit our definition of a recipe (a **step-by-step how-to guide** for **accomplishing a specific task** in Astro). They may also be tested by a Team Docs member who will attempt to follow your recipe and make sure it works. So, while this may seem like a tiny PR, please know that there is work going on behind the scenes and it may take some time to properly evaluate your recipe!

### Is my guide a recipe?

Our recipe format is inspired by Diataxis's [how-to guides](https://diataxis.fr/how-to-guides/). Recipes:

- Provide step-by-step instructions
- Meet a user at a specific starting point (see our [Prerequisites](https://docs.astro.build/en/recipes/build-forms-api/#prerequisites) sections)
- Explain how to accomplish a specific task
- Use real-world examples

See our [HTML Forms](https://docs.astro.build/en/recipes/build-forms-api/) recipe as an example. It teaches a specific, practical goal (how to build and handle a form). It provides an example that can be modified and incorporated into your project. It uses step-by-step instructions and keeps explanations to a minimum.

Examples that would not be considered recipes:
- A blog post in narrative form that reports on what you did instead of structuring concise instructions for the reader to follow. (e.g. "How I finally got content collections set up with my custom remark plugin in my Astro project")
- A walk-through that teaches more than one task. (e.g. "How to set up Vue, TypeScript, and Partytown in Astro")
- A conceptual explanation of a topic, instead of a how-to guide that leads the reader through completing a specific task. (e.g. "How partial hydration works in Astro")

Like all contributions to our docs, take a look at the [WRITING.md](https://github.com/withastro/docs/blob/main/WRITING.md
) and [CONTRIBUTING.md](https://github.com/withastro/docs/blob/main/CONTRIBUTING.md
) files for guidance on drafting your PR.

Astro docs welcomes contributions that:

- Edit an existing guide with corrected content or [new links](#add-new-links), by PRing the existing file in the docs repo.
- Add a new CMS, Deploy or Migration guide. (See below for instructions to create the required files in Docs.)
- Add a new official recipe, by PRing a new page to `src/content/docs/recipes/`
- Add a new community recipe by PRing a link to `src/content/docs/guides/recipes.mdx`
## CMS, Deploy and Migrate

## CMS, Deploy, and Migrate

The `src/content/guides/` directory in the docs has three subdirectories for established guides:
The `src/content/guides/` directory in the docs has three subdirectories for established guide categories:

- `cms/`
- `deploy/`
@@ -28,7 +64,7 @@ These require:
- A logo in `public/logos/`.
- An update to [`src/data/logo.ts`](https://github.com/withastro/docs/blob/main/src/data/logos.ts) to add the logo.

### Adding a new guide
### Add a new guide

1. Add a new `.mdx` file to one of the subdirectories. Copy the contents of an existing file, and change the `title` and `description` in the frontmatter.

@@ -38,44 +74,21 @@ These require:

4. Update [`src/data/logo.ts`](https://github.com/withastro/docs/blob/main/src/data/logos.ts) to add the logo.

### Stubs
### Add a new stub

Some guides are marked as `stub: true` in the frontmatter. These are not yet full guides, but instead include introductory content and link to external resources.

If you don't have a full guide yet, feel free to create a stub with an introductory paragraph and a “Community Resources” and/or “Official Resources” section. See [this example PR creating a new stub](https://github.com/withastro/docs/pull/2336/files).
If you don't have a full guide yet, feel free to create a stub with an introductory paragraph and a “Community Resources” and/or “Official Resources” section following the steps above. See [this example PR creating a new stub](https://github.com/withastro/docs/pull/2336/files).

You can expand a stub, even if it's an incremental improvement. For example, you can expand a CMS guide by adding an "Integrating with Astro" section to explain how to connect the CMS to Astro. You can also provide a step-by-step section to use that integration to build something. (See [Making a blog with Astro and Contentful](https://docs.astro.build/en/guides/cms/contentful/#making-a-blog-with-astro-and-contentful).)

### Add new links

The CMS, Deploy, and Migrate guides all have sections for external links. You can add a new link by [creating a PR](https://github.com/withastro/docs/blob/main/CONTRIBUTING.md).

## More Recipes page

This landing page shows how-to guides that don't fit in the above categories.

The Official Recipes section is for officially maintained recipes, found in the `src/content/guides/recipes` folder. Like the rest of our docs, these must meet the standards of our [Writing Guide](https://github.com/withastro/docs/blob/main/WRITING.md) and require long-term maintenance to make sure they're up to date.

Community Recipes are for external links that fit the definition of a recipe: short, focused how-to guides. This lets us include community resources without requiring long-term maintenance.

### Is my guide a recipe?

Our recipe format is inspired by Diataxis's [how-to guides](https://diataxis.fr/how-to-guides/). Recipes:

- Provide step-by-step instructions
- Meet a user at a specific starting point (see our [Prerequisites](https://docs.astro.build/en/recipes/build-forms-api/#prerequisites) sections)
- Explain how to accomplish a specific task
- Use real-world examples

See our [HTML Forms](https://docs.astro.build/en/recipes/build-forms-api/) recipe as an example. It teaches a specific, practical goal (how to build and handle a form). It provides an example that can be modified and incorporated into your project. It uses step-by-step instructions and keeps explanations to a minimum.

### Community Recipes

You can share a published recipe in our “Community Recipes” section. This includes posts on a personal or company blog, or on your preferred blogging platform like [DEV.to](https://dev.to/). This follows the IndieWeb principle of “Publish (on your) Own Site, Syndicate Elsewhere” (often abbreviated to [POSSE](https://indieweb.org/POSSE)).

After you publish your article, [open a PR adding a link to this page](https://github.com/withastro/docs/edit/main/src/content/docs/en/recipes.mdx).
## Add a new official recipe

### Official Recipes
The Official Recipes section is for officially maintained recipes, found in the `src/content/guides/recipes` folder, that do not fit into one of our pre-existing categories. Like the rest of our docs, these must meet the standards of our [Writing Guide](https://github.com/withastro/docs/blob/main/WRITING.md) and require long-term maintenance to make sure they're up to date.

To add an official recipe:

Loading

0 comments on commit b7b4142

Please sign in to comment.