forked from tauri-apps/tauri-docs
-
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Showing
385 changed files
with
52,315 additions
and
138 deletions.
There are no files selected for viewing
Validating CODEOWNERS rules …
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,5 @@ | ||
# Order is important; the last matching pattern takes the most precedence. | ||
* @tauri-apps/wg-doc | ||
|
||
# Disabled until wg-devops has active members | ||
# .github @tauri-apps/wg-devops |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,113 @@ | ||
# Contributing | ||
|
||
Welcome to Tauri Docs! We're excited to have you 🥳 | ||
|
||
[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/tauri-apps/tauri-docs/tree/v2) | ||
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://codespaces.new/tauri-apps/tauri-docs/tree/v2) | ||
|
||
There are a number of ways to get involved: | ||
|
||
- See if there are any [good first issues](https://github.com/tauri-apps/tauri-docs/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) that catch your eye | ||
- [Write a guide or recipe](#write-documentation) | ||
- [Translating existing documentation](#translations-i18n) | ||
|
||
Reach out to us on [Discord](https://discord.com/invite/tauri) on the [`#docs` channel](https://discord.com/channels/616186924390023171/662624589037436928) if you have any questions! | ||
|
||
## Getting Started | ||
|
||
1. Clone this repo | ||
2. Run `pnpm i && pnpm dev:setup` | ||
3. Run `pnpm dev` to start the local server | ||
|
||
### Gitpod | ||
|
||
[Allow Gitpod to open new tabs](https://www.gitpod.io/docs/configure/user-settings/browser-settings) so you immediately when the environment is done loading get a new tab popping up with the documentation. | ||
|
||
## Write Documentation | ||
|
||
We have the following types of documents that roughly follow the types defined by [Diátaxis](https://diataxis.fr/): | ||
|
||
- **[Guide](#guide)**: Learning-oriented | ||
- **[Recipe](#recipe)**: Task-oriented | ||
- **[Reference](#recipe)**: Information-oriented | ||
- **[Blog Post](#blog-post)**: Understanding-oriented | ||
|
||
Use this chart to help you figure out where the right place for your content is: | ||
|
||
| If the content describes… | …and serves the user's… | …then it must belong to… | | ||
| ------------------------- | ----------------------- | ------------------------- | | ||
| practical steps | study | [a guide](#guide) | | ||
| practical steps | work | [a recipe](#recipe) | | ||
| theoretical knowledge | work | [a reference](#reference) | | ||
| theoretical knowledge | study | [a blog post](#blog-post) | | ||
|
||
### Writing for Prerelease | ||
|
||
While Tauri 2.0 is still in the prerelease stage people follow these guidelines for writing documentation: | ||
|
||
- Refer to Tauri 2.0 as if it's released now (so that copy doesn't need to be updated upon release) | ||
- Write any code so that it works **now** but... | ||
- Annotate 2.0 code with `{/* FIXME: 2.0 */}` (.mdx files) or `<!-- FIXME: 2.0 -->` (.md files) so that we can easily find and fix any of those upon release (feel free to add in what the code should be upon release in additional comments) | ||
|
||
### Writing Style | ||
|
||
**Dictionary** | ||
|
||
| Word | Description | | ||
| -------- | ------------------------------------ | | ||
| app | A Tauri app, prefer over application | | ||
| web view | Where the UI is rendered | | ||
|
||
- Use an [oxford comma](https://www.grammarly.com/blog/what-is-the-oxford-comma-and-why-do-people-care-so-much-about-it/) in paragraphs, but not in headings and titles | ||
- Use [title case](https://apastyle.apa.org/style-grammar-guidelines/capitalization/title-case) for headings and titles | ||
- Make headings as succinct as possible to help the reader quickly find the content they need | ||
- Use [simple present tense](https://www.grammarly.com/blog/simple-present/) for verbs | ||
|
||
### Guide | ||
|
||
Located in [`/src/content/docs/2/guide/`](https://github.com/tauri-apps/tauri-docs/tree/starlight/src/content/docs/2/guide) | ||
|
||
Guides are learning-oriented and take the reader through a specific journey such as starting a new project, and overview of a specific feature, or how to follow a specific flow such as building and bundling their app. They follow a similar philosophy to [tutorials in Diátaxis](https://diataxis.fr/tutorials). | ||
|
||
The reader should be familiar with the concepts covered by the end of the guide and should set them up with the knowledge required to being experimenting with that topic themselves. | ||
|
||
### Recipe | ||
|
||
Located in [`/src/content/docs/2/recipe/`](https://github.com/tauri-apps/tauri-docs/tree/starlight/src/content/docs/2/recipe) | ||
|
||
Recipes are designed to guide the reader through a specific task similar and have a clear outcome and objective. This could be something like setting up authentication using Firebase, adding a Python binary using sidecar, or requesting admin access on a user's machine. They are similar to [how-to guides in Diátaxis](https://diataxis.fr/how-to-guides) (not to be confused with our own guides mentioned above). | ||
|
||
The prerequisites for a recipe should be clearly stated. If there are a lot of steps required before getting into the relevant information about the recipe then you may want to link out to another guide, recipe, or external resource and state those as a prerequisite at the top of the recipe. | ||
|
||
### Reference | ||
|
||
Located in [`/src/content/docs/2/reference/`](https://github.com/tauri-apps/tauri-docs/tree/starlight/src/content/docs/2/reference), although they should be auto-generated when possible. | ||
|
||
References are where all the nuts and bolts of Tauri's API are documented. These should be generated from upstream repos when possible and written following the best practices described by [references in Diátaxix](https://diataxis.fr/reference). | ||
|
||
These should be as succinct and to the point as possible so that the reader can quickly find the relevant information. | ||
|
||
If you'd like to view the API references locally then you must run `pnpm dev:setup` before `pnpm dev` to initialize all of the submodules. Now the `http://localhost:3000/2/reference/` routes are available to preview. | ||
|
||
### Blog Post | ||
|
||
Not yet created, will be added in the future. | ||
|
||
Topics that are around understanding something can be written as a blog post (we welcome submissions to the Tauri blog from anyone). Blog posts are a good option because they help the reader understand that information is accurate at the time of writing (and of course can always be updated later if it becomes stale). Blog posts follow the goals of [explanation in Diátaxis](https://diataxis.fr/explanation), but not all blog posts necessarily fit this specific format. | ||
|
||
### Diagrams | ||
|
||
We use [Astro D2](https://astro-d2.vercel.app/) to generate diagrams. Because Netlify does not support compiling the diagrams in its end we have to push the prebuilt images manually. This is annoying, but not the end of the world seeing as we've previously been pushing the images manually anyway. | ||
|
||
If you make an update to a diagram you'll need to [install D2](https://github.com/terrastruct/d2/blob/master/docs/INSTALL.md) on your system, then when you run either the `build` or `dev` commands you'll need to enable building the diagrams by setting the environment variable `CONTEXT=d2`. | ||
|
||
```sh | ||
# Adapt the command as relevant for your system to define the variable | ||
CONTEXT=d2 pnpm dev | ||
``` | ||
|
||
## Translations (i18n) | ||
|
||
Thanks for your interest in helping to translate the documentation! Visit the [translation status page](https://v2.tauri.app/contribute/translate-status) to see which docs are ready for translation, need updated, or need reviewed. | ||
|
||
Read the [Translating Guide](./TRANSLATING.md) for more information. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,9 @@ | ||
# Copyright 2019-2024 Tauri Programme within The Commons Conservancy | ||
# SPDX-License-Identifier: Apache-2.0 | ||
# SPDX-License-Identifier: MIT | ||
|
||
blank_issues_enabled: true | ||
contact_links: | ||
- name: 💬 Discord Chat | ||
url: https://discord.com/invite/tauri | ||
about: Ask questions and talk to other Tauri users and the maintainers |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,50 @@ | ||
# Copyright 2019-2024 Tauri Programme within The Commons Conservancy | ||
# SPDX-License-Identifier: Apache-2.0 | ||
# SPDX-License-Identifier: MIT | ||
|
||
name: 🤔 v2 Page Request | ||
title: '[request] ' | ||
description: Request a new page or updated content | ||
labels: | ||
- enhancement | ||
- discuss | ||
|
||
body: | ||
- type: input | ||
id: question | ||
attributes: | ||
label: Question you want answered | ||
description: The question you were trying to get answered by going to the website and couldn't find. Even if you weren't looking to get a specific question answered try to encapsulate the essence of your issue in the form of a question. | ||
placeholder: "How do I register a new State?" | ||
validations: | ||
required: true | ||
|
||
- type: textarea | ||
id: answer | ||
attributes: | ||
label: Where did you look for an answer? | ||
description: Think back on how you navigate the site in order to find the answer to your question so we get a better idea of how people interact with the site. | ||
placeholder: First I tried searching for the issue, then I went to the sidebar to find a relevant page... | ||
validations: | ||
required: true | ||
|
||
- type: input | ||
id: url | ||
attributes: | ||
label: Page URL | ||
description: If applicable, copy-paste the URL to the page you want updated. | ||
placeholder: "https://v2.tauri.app/some/specific/page" | ||
|
||
- type: textarea | ||
id: context | ||
attributes: | ||
label: Additional context | ||
description: Add any other context about the problem here. | ||
|
||
- type: checkboxes | ||
attributes: | ||
label: Are you willing to work on this yourself? | ||
description: If so don't hesitate to reach out on Discord to us, we're more than happy to help you get set up with contributing! | ||
options: | ||
- label: I want to work on this myself | ||
required: false |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
<!-- Thank you for opening a PR! We really appreciate you taking the time to help out 🙌 --> | ||
|
||
#### Description | ||
<!-- Translators, try to follow this pattern when naming your PRs: | ||
"i18n(language code): (short description)" --> | ||
- What does this PR change? Give us a brief description. <!-- If it's an update try adding the commits as reference --> | ||
- Closes # <!-- Add an issue number if this PR will close it or remove it. --> | ||
|
||
<!-- | ||
Here's what will happen next: | ||
1. Our GitHub bots will run to check your changes. | ||
If they spot any broken links you will see some error messages on this PR. | ||
Don't hesitate to ask any questions if you're not sure what these mean! | ||
2. In a few minutes, you'll be able to see a preview of your changes on Netlify 🥳 | ||
3. One or more of our maintainers will take a look and may ask you to make changes. | ||
We try to be responsive, but don't worry if this takes a day or two. | ||
4. Reach out to us on Discord with any questions along the way: | ||
https://discord.com/invite/tauri | ||
--> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,88 @@ | ||
# Translations (i18n) | ||
|
||
Thanks for your interest in helping translate the Tauri docs! Visit the [translation status page](https://v2.tauri.app/contribute/translate-status) to see which docs are ready for translation, need updated, or need reviewed. | ||
|
||
To ensure a translation is consistent across multiple contributions, be sure to [communicate with others contributors in the `#docs` channel on Discord](https://discord.com/invite/tauri) and consult with reliable external resources such as [Microsoft terminology search](https://msit.powerbi.com/view?r=eyJrIjoiODJmYjU4Y2YtM2M0ZC00YzYxLWE1YTktNzFjYmYxNTAxNjQ0IiwidCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsImMiOjV9) during translation. | ||
|
||
## Enabling a Language | ||
|
||
If you seek to contribute but find your language missing please let us know in https://github.com/tauri-apps/tauri-docs/issues/1611. Once we have enough support for a particular language then we'll be able to enable it with the community's support. | ||
|
||
### Maintainer Checklist for Adding New Languages | ||
|
||
- Update https://github.com/tauri-apps/tauri-docs/blob/v2/locales.json | ||
- Update https://github.com/tauri-apps/tauri-docs/blob/v2/.github/labeler.yml | ||
|
||
## Starting a Translation | ||
|
||
Before you start working on a translation, look through the [open pull requests](https://v2.tauri.app/contribute/translate-status#needs-review) to see if anyone else is already working on the page for that language. | ||
|
||
If that page isn't in the list, then now it's time for you to lead the effort! So here's how to start: | ||
|
||
1. Head to [translation status page](https://v2.tauri.app/contribute/translate-status). | ||
2. Look for missing translation in corresponding languages. | ||
3. Make sure no one else has been working on the corresponding page. | ||
4. Click `Create page +` which will help you automagically fork the repository and create the corresponding page. You might want to copy the contents of English page as a starting point. | ||
5. Translate the page following the [translation guidelines](#translation-guidelines). | ||
6. Once your translation is done, initiate a pull request. | ||
|
||
Note that you may submit a draft pull request before your translation is complete: e.g., you may want to ask for help with translations or simply indicate to others that you're already translating a specific page. However, your pull request will not be merged until the translation is complete. | ||
|
||
## Updating a Translation | ||
|
||
### Corrections | ||
|
||
If you notice spelling or grammar errors, typos, or opportunities for better phrasing, open a pull request with your suggested fix. If you see a problem that you aren't sure of or don't have time to fix, open an issue. | ||
|
||
### Broken Links | ||
|
||
When broken links are found, try to fix them across all translations. Ideally, only update the linked URLs, so that translation review will not be necessary. | ||
|
||
## Translation Guidelines | ||
|
||
Here are some guidelines to help with the translation. | ||
|
||
**Markdown Formatting** | ||
|
||
- [ ] Preserve the Markdown formatting. This includes headers (#, ##, etc.), lists (*, -, 1.), and inline styles like bold, italic, and code. | ||
- [ ] Ensure that links ([link text](URL)) remain functional and direct to the correct locations. | ||
- [ ] Ensure code blocks (triple backticks ```) are unchanged in terms of their syntax and content. | ||
- [ ] Double-check tables, making sure their structure remains intact. Using the Prettier formatter is a great way to do this. | ||
|
||
**Terminology** | ||
|
||
- [ ] Familiarize yourself with key Tauri terms and ensure they're translated consistently. It may be helpful to look at other, already translated pages as a reference. | ||
- [ ] For some terms, it might be appropriate to keep them in English and provide a translation in parentheses. | ||
- [ ] If a term has no definitive way to translate, be sure to [communicate with others contributors in the `#docs` channel on Discord](https://discord.com/invite/tauri) or through pull request and consult with reliable external resources such as [Microsoft terminology search](https://msit.powerbi.com/view?r=eyJrIjoiODJmYjU4Y2YtM2M0ZC00YzYxLWE1YTktNzFjYmYxNTAxNjQ0IiwidCI6IjcyZjk4OGJmLTg2ZjEtNDFhZi05MWFiLTJkN2NkMDExZGI0NyIsImMiOjV9). | ||
|
||
**Code and Command Examples** | ||
|
||
- [ ] Avoid translating code unless it contains explanatory comments. Translated comments should retain the original meaning. | ||
- [ ] Ensure command-line examples remain functional. Only translate the descriptive parts, not the actual commands. | ||
|
||
**Link Descriptions** | ||
|
||
- [ ] If link descriptions (text that appears when you hover over a link) are present, make sure to translate them, but ensure they still describe the link's destination correctly. | ||
|
||
**Consistency** | ||
|
||
- [ ] Ensure that the terminology and style are consistent throughout the document. | ||
- [ ] If the document refers to other sections within itself, double-check that these references are accurate post-translation. | ||
|
||
**Cultural Considerations** | ||
|
||
- [ ] Ensure that examples, metaphors, or idioms are culturally relevant or adapt them so that they are. | ||
- [ ] Avoid terms or examples that might be considered offensive or inappropriate in the target language or culture. | ||
|
||
**Images and Alt Text** | ||
|
||
- [ ] If the document contains images with text, consider whether the text in the image needs to be translated. | ||
- [ ] Translate the alt text (a description of the image for accessibility purposes) for each image. | ||
|
||
**Feedback** | ||
|
||
- [ ] If there are parts of the original document that are unclear or might be misunderstood, communicate with the original author or a knowledgeable person to seek clarity. | ||
|
||
Remember, the main goal of the translation is to make the content as accessible and clear to the new audience as it was to the original audience. Always prioritize clarity and accuracy. | ||
|
||
Thank you for your interest in contributing; we're excited to have you! Reach out on the [`#docs` channel on Discord](https://discord.com/invite/tauri) if you have any questions along the way. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,19 @@ | ||
# See https://github.com/actions/labeler | ||
|
||
i18n: | ||
- src/content/docs/es/**/* | ||
- src/content/docs/fr/**/* | ||
- src/content/docs/it/**/* | ||
- src/content/docs/zh-cn/**/* | ||
|
||
"i18n: es": | ||
- src/content/docs/es/**/* | ||
|
||
"i18n: fr": | ||
- src/content/docs/fr/**/* | ||
|
||
"i18n: it": | ||
- src/content/docs/it/**/* | ||
|
||
"i18n: zh-cn": | ||
- src/content/docs/zh-cn/**/* |
Oops, something went wrong.