diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 45f4d4b4410..fbde0027a03 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -20,9 +20,9 @@ jobs: name: Run unit tests runs-on: ubuntu-20.04 steps: - - uses: actions/checkout@v3 - - uses: pnpm/action-setup@v2 - - uses: actions/setup-node@v3 + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v3 + - uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'pnpm' @@ -35,13 +35,13 @@ jobs: runs-on: ubuntu-20.04 steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Setup PNPM - uses: pnpm/action-setup@v2 + uses: pnpm/action-setup@v3 - name: Setup Node - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'pnpm' @@ -63,9 +63,9 @@ jobs: name: Docs site builds on Windows runs-on: windows-latest steps: - - uses: actions/checkout@v3 - - uses: pnpm/action-setup@v2 - - uses: actions/setup-node@v3 + - uses: actions/checkout@v4 + - uses: pnpm/action-setup@v3 + - uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'pnpm' @@ -79,13 +79,13 @@ jobs: runs-on: ubuntu-20.04 steps: - name: Checkout - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Setup PNPM - uses: pnpm/action-setup@v2 + uses: pnpm/action-setup@v3 - name: Setup Node - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: ${{ env.NODE_VERSION }} cache: 'pnpm' diff --git a/.github/workflows/format.yml b/.github/workflows/format.yml index 4156fc401b2..b5de351b608 100644 --- a/.github/workflows/format.yml +++ b/.github/workflows/format.yml @@ -10,13 +10,13 @@ jobs: runs-on: ubuntu-latest steps: - name: Check out code using Git - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: ref: ${{ github.head_ref }} # Needs access to push to main token: ${{ secrets.FREDKBOT_GITHUB_TOKEN }} - - uses: pnpm/action-setup@v2 - - uses: actions/setup-node@v3 + - uses: pnpm/action-setup@v3 + - uses: actions/setup-node@v4 with: node-version: 18 cache: 'pnpm' @@ -24,7 +24,7 @@ jobs: - name: Format with Prettier run: pnpm format - name: Commit changes - uses: stefanzweifel/git-auto-commit-action@v4 + uses: stefanzweifel/git-auto-commit-action@v5 with: commit_message: '[ci] format' branch: ${{ github.head_ref }} diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8dc3aafde6d..fe406013740 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -12,16 +12,16 @@ jobs: runs-on: ubuntu-latest steps: - name: Checkout Repo - uses: actions/checkout@v3 + uses: actions/checkout@v4 with: # This makes Actions fetch all Git history so that Changesets can generate changelogs with the correct commits fetch-depth: 0 - name: Setup PNPM - uses: pnpm/action-setup@v2 + uses: pnpm/action-setup@v3 - name: Setup Node - uses: actions/setup-node@v3 + uses: actions/setup-node@v4 with: node-version: 18 cache: 'pnpm' diff --git a/.github/workflows/size-limit.yml b/.github/workflows/size-limit.yml index b84554e10fd..f2586e259a9 100644 --- a/.github/workflows/size-limit.yml +++ b/.github/workflows/size-limit.yml @@ -18,7 +18,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - uses: pnpm/action-setup@v2 + - uses: pnpm/action-setup@v3 - run: pnpm i - run: 'pnpm build:examples' - run: pnpm size @@ -31,7 +31,7 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - - uses: pnpm/action-setup@v2 + - uses: pnpm/action-setup@v3 - name: Run size-limit uses: andresz1/size-limit-action@dd31dce7dcc72a041fd3e49abf0502b13fc4ce05 with: diff --git a/.github/workflows/welcome-bot.yml b/.github/workflows/welcome-bot.yml index 30994f4a411..a433fe8088b 100644 --- a/.github/workflows/welcome-bot.yml +++ b/.github/workflows/welcome-bot.yml @@ -13,7 +13,7 @@ jobs: name: Welcome First-Time Contributors runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - uses: zephyrproject-rtos/action-first-interaction@7e6446f8439d8b4399169880c36a3a12b5747699 with: repo-token: ${{ secrets.FREDKBOT_GITHUB_TOKEN }} diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs index 40ec5df1459..e83c6ee6589 100644 --- a/docs/astro.config.mjs +++ b/docs/astro.config.mjs @@ -136,6 +136,7 @@ export default defineConfig({ id: 'Dampak terhadap lingkungan', 'zh-CN': '环境影响', 'pt-BR': 'Impacto Ambiental', + 'pt-PT': 'Impacto Ambiental', ko: '환경적 영향', tr: 'Çevre Etkisi', ru: 'Влияние на окружающую среду', diff --git a/docs/src/content/docs/it/guides/pages.mdx b/docs/src/content/docs/it/guides/pages.mdx index a9e5d5bcb11..375d5a74a9e 100644 --- a/docs/src/content/docs/it/guides/pages.mdx +++ b/docs/src/content/docs/it/guides/pages.mdx @@ -104,15 +104,37 @@ Le seguenti proprietà differiscono dal frontmatter di Markdown: - La proprietà [`slug`](/it/reference/frontmatter/#slug) non è supportata e viene impostata automaticamente in base all'URL della pagina personalizzata. - L'opzione [`editUrl`](/it/reference/frontmatter/#editurl) richiede un URL per visualizzare un link di modifica. -- La proprietà [`sidebar`](/it/reference/frontmatter/#sidebar) non è supportata. Nel frontmatter di Markdown, questa opzione consente la personalizzazione dei [gruppi di link generati automaticamente](/it/reference/configuration/#sidebar), che non è applicabile alle pagine che utilizzano il componente ``. - -{/* ##### `sidebar` */} - -{/* **tipo:** `SidebarEntry[] | undefined` */} -{/* **predefinito:** la barra laterale generata in base alla [configurazione globale `sidebar`](/reference/configuration/#sidebar) */} - -{/* Fornisce una barra laterale di navigazione personalizzata per questo sito. */} -{/* Se non impostato, la pagina utilizzerà la barra laterale globale predefinita. */} +- La proprietà del frontmatter [`sidebar`](/it/reference/frontmatter/#sidebar) per personalizzare come appare la pagina in [gruppi di link autogenerati](/it/reference/configuration/#sidebar) non è disponibile. Le pagine che utilizzano il componente `` non fanno parte di una collezione e non possono essere aggiunte a un gruppo di barra laterale autogenerato. + +##### `sidebar` + +**tipo:** `SidebarEntry[]` +**predefinito:** la barra laterale generata in base alla [configurazione globale `sidebar`](/it/reference/configuration/#sidebar) + +Fornisce una barra laterale di navigazione personalizzata per questa pagina. +Se non impostato, la pagina utilizzerà la barra laterale globale predefinita. + +Ad esempio, la pagina seguente sovrascrive la barra laterale predefinita con un link alla homepage e un gruppo di link a diverse costellazioni. +La pagina corrente nella barra laterale è impostata utilizzando la proprietà `isCurrent` e un `badge` opzionale è stato aggiunto a un elemento di link. + +```astro {3-13} + + Contenuto di esempio. + +``` ##### `hasSidebar` diff --git a/docs/src/content/docs/it/resources/plugins.mdx b/docs/src/content/docs/it/resources/plugins.mdx index 5a86a2c77c1..c370bb69cdb 100644 --- a/docs/src/content/docs/it/resources/plugins.mdx +++ b/docs/src/content/docs/it/resources/plugins.mdx @@ -38,6 +38,26 @@ Estendi il tuo sito con plugin ufficiali supportati dal team Starlight e plugin title="starlight-typedoc" description="Genera pagine Starlight da TypeScript usando TypeDoc." /> + + + + ## Strumenti e integrazioni della community @@ -52,16 +72,6 @@ Questi strumenti e integrazioni della community possono essere utilizzati per ag title="FeelBack" description="Aggiungi un sistema di feedback utente alle tue pagine di documentazione." /> - - + diff --git a/docs/src/content/docs/pt-pt/environmental-impact.md b/docs/src/content/docs/pt-pt/environmental-impact.md new file mode 100644 index 00000000000..e1c687fad1d --- /dev/null +++ b/docs/src/content/docs/pt-pt/environmental-impact.md @@ -0,0 +1,140 @@ +--- +title: Documentação ecológica +description: Aprenda como o Starlight te pode ajudar a construir sites de documentação mais ecológicos e reduzir a pegada de carbono. +--- + +As estimativas para o impacto climático da indústria web variam entre [2%][sf] e [4% das emissões globais de carbono][bbc], aproximadamente o equivalente às emissões da indústria aeronáutica. +Há vários fatores complexos no cálculo do impacto ecológico de um website, mas este guia inclui algumas dicas para reduzir a pegada ambiental do seu site de documentação. + +A boa noticía é que, escolher o Starlight já é um bom começo! +De acordo com o "Website Carbon Calculator", este site é [mais limpo do que 99% das páginas web testadas][sl-carbon], produzindo 0.01g de CO₂ por cada visita à página. + +## Peso da página + +Quanto mais dados uma página web transfere mais recursos energéticos são necessários. +De acordo com [dados do HTTP Archive][http], em Abril de 2023, uma página web mediana necessitava que o utilizador baixasse mais de 2,000 KB. + +O Starlight constrói páginas que são o mais leve possível. +Por exemplo, na primeira visita, um utilizador vai descarregar menos do que 50 KB de dados comprimidos, ou seja, apenas 2.5% da mediana indicada pelo HTTP Archive. +Com uma boa estratégia de _cache_, as navegações subsequentes podem descarregar tão pouco quanto 10 KB. + +### Imagens + +Enquanto o Starlight providencia uma boa base, as imagens que você adicionar à sua documentação podem aumentar o peso da sua página rapidamente. +O Starlight usa o [suporte a assets otimizados][assets] do Astro para otimizar imagens locais nos seus arquivos Markdown e MDX. + +### Componentes de UI + +Os componentes construídos com frameworks de UI como React ou Vue podem facilmente adicionar grandes quantidades de JavaScript a uma página. +Porque o Starlight é construído com o Astro, e graças às [Ilhas Astro][islands], esses componentes carregam, **por padrão, zero código JavaScript no lado do cliente**. + +### _Cache_ + +A _Cache_ é usada para controlar por quanto tempo um navegador armazena e reutiliza os dados já descarregados. +Uma boa estratégia de _caching_ garante que um utilizador receba o conteúdo novo o mais cedo possível assim que ele muda, mas também evita descarregar inutil e repetidamente o mesmo conteúdo sem que ele mude. + +A forma mais comum de configurar a _cache_ é com o [header HTTP `Cache-Control`][cache]. +Ao utilizar o Starlight, você pode definir um grande tempo de cache para todo o conteúdo do diretório `/_astro/`. +Este diretório contém CSS, JavaScript e outros artefactos em _bundle_ que podem ser seguramente _cached_ para sempre, reduzindo assim downloads desnecessários: + +``` +Cache-Control: public, max-age=604800, immutable +``` + +A forma de configurar a _cache_ depende do seu alojamento web. Por exemplo, o Vercel aplica por você esta estratégia de _cache_ sem necessidade de configuração adicional, já a definição de [cabeçalhos customizados para Netlify][ntl-headers] necessita que adicione um arquivo `public/_headers` ao seu projeto: + +``` +/_astro/* + Cache-Control: public + Cache-Control: max-age=604800 + Cache-Control: immutable +``` + +[cache]: https://csswizardry.com/2019/03/cache-control-for-civilians/ +[ntl-headers]: https://docs.netlify.com/routing/headers/ + +## Consumo de energia + +A forma com que uma página web é construída pode ter impacto na energia necessária para executá-la no dispositivo de um utilizador. +Por utilizar JavaScript ao mínimo, o Starlight reduz a quantidade de energia de processamento que o celular, tablet ou computador de um utilizador precisa para carregar e renderizar páginas. + +Tenha atenção ao adicionar funcionalidades como scripts de rastreamento de _Analytics_ ou conteúdo cheio de JavaScript como embeds de vídeo já que estes podem aumentar o consumo de energia da página. +Se você precisa de _Analytics_, considere escolher uma opção leve como [Cabin][cabin], [Fathom][fathom] ou [Plausible][plausible]. +Embeds como vídeos do YouTube e Vimeo podem ser melhorados se [carregar o vídeo mediante a interação do usuário][lazy-video]. +Pacotes como o [`astro-embed`][embed] podem ajudá-lo com alguns dos serviços comuns. + +:::tip[Sabia que?] +Fazer parse e compilação de JavaScript é uma das tarefas mais caras que os navegadores tem que fazer. +Comparado com a renderização de uma imagem JPEG de mesmo tamanho, [o JavaScript pode levar mais do que 30 vezes o tempo para processar][cost-of-js]. +::: + +[cabin]: https://withcabin.com/ +[fathom]: https://usefathom.com/ +[plausible]: https://plausible.io/ +[lazy-video]: https://web.dev/iframe-lazy-loading/ +[embed]: https://www.npmjs.com/package/astro-embed +[cost-of-js]: https://medium.com/dev-channel/the-cost-of-javascript-84009f51e99e + +## Alojamento + +O lugar onde uma página web é alojada pode ter um grande impacto no quão amigável ao ambiente o seu site de documentação é. +Os centros de dados e de servidores podem ter um grande impacto ecológico, incluindo alto consumo de eletricidade e uso intensivo de água. + +Escolher um alojamento que utiliza energia renovável significará menos emissões de carbono para o seu site. A [Green Web Directory][gwb] é uma ferramenta que poderá ajudá-lo a encontrar empresas de alojamento. + +[gwb]: https://www.thegreenwebfoundation.org/directory/ + +## Comparações + +Está curioso para comparar com os outros frameworks de documentação? +Estes testes realizados com o [Website Carbon Calculator][wcc] comparam páginas semelhantes construídas com diferentes ferramentas. + +| Framework | CO₂ por visita da página | +| --------------------------- | ------------------------ | +| [Starlight][sl-carbon] | 0.01g | +| [VitePress][vp-carbon] | 0.05g | +| [Docus][dc-carbon] | 0.05g | +| [Sphinx][sx-carbon] | 0.07g | +| [MkDocs][mk-carbon] | 0.10g | +| [Nextra][nx-carbon] | 0.11g | +| [docsify][dy-carbon] | 0.11g | +| [Docusaurus][ds-carbon] | 0.24g | +| [Read the Docs][rtd-carbon] | 0.24g | +| [GitBook][gb-carbon] | 0.71g | + +Dados recolhidos a 14 de Maio de 2023. Clique num dos links para ver os valores atualizados. + +[sl-carbon]: https://www.websitecarbon.com/website/starlight-astro-build-getting-started/ +[vp-carbon]: https://www.websitecarbon.com/website/vitepress-dev-guide-what-is-vitepress/ +[dc-carbon]: https://www.websitecarbon.com/website/docus-dev-introduction-getting-started/ +[sx-carbon]: https://www.websitecarbon.com/website/sphinx-doc-org-en-master-usage-quickstart-html/ +[mk-carbon]: https://www.websitecarbon.com/website/mkdocs-org-getting-started/ +[nx-carbon]: https://www.websitecarbon.com/website/nextra-site-docs-docs-theme-start/ +[dy-carbon]: https://www.websitecarbon.com/website/docsify-js-org/ +[ds-carbon]: https://www.websitecarbon.com/website/docusaurus-io-docs/ +[rtd-carbon]: https://www.websitecarbon.com/website/docs-readthedocs-io-en-stable-index-html/ +[gb-carbon]: https://www.websitecarbon.com/website/docs-gitbook-com/ + +## Mais recursos + +### Ferramentas + +- [Website Carbon Calculator][wcc] +- [GreenFrame](https://greenframe.io/) +- [Ecograder](https://ecograder.com/) +- [WebPageTest Carbon Control](https://www.webpagetest.org/carbon-control/) +- [Ecoping](https://ecoping.earth/) + +### Artigos e palestras + +- [“Building a greener web”](https://youtu.be/EfPoOt7T5lg), palestra por Michelle Barker +- [“Sustainable Web Development Strategies Within An Organization”](https://www.smashingmagazine.com/2022/10/sustainable-web-development-strategies-organization/), artigo por Michelle Barker +- [“A sustainable web for everyone”](https://2021.stateofthebrowser.com/speakers/tom-greenwood/), palestra por Tom Greenwood +- [“How Web Content Can Affect Power Usage”](https://webkit.org/blog/8970/how-web-content-can-affect-power-usage/), artigo por Benjamin Poulain e Simon Fraser + +[sf]: https://www.sciencefocus.com/science/what-is-the-carbon-footprint-of-the-internet/ +[bbc]: https://www.bbc.com/future/article/20200305-why-your-internet-habits-are-not-as-clean-as-you-think +[http]: https://httparchive.org/reports/state-of-the-web +[assets]: https://docs.astro.build/pt-pt/guides/assets/ +[islands]: https://docs.astro.build/pt-pt/concepts/islands/ +[wcc]: https://www.websitecarbon.com/ diff --git a/docs/src/content/docs/zh-cn/resources/plugins.mdx b/docs/src/content/docs/zh-cn/resources/plugins.mdx index a1e924cecc2..1290afec37d 100644 --- a/docs/src/content/docs/zh-cn/resources/plugins.mdx +++ b/docs/src/content/docs/zh-cn/resources/plugins.mdx @@ -37,6 +37,26 @@ sidebar: title="starlight-typedoc" description=" 使用 TypeDoc 从 TypeScript 生成 Starlight 页面。" /> + + + + ## 社区工具和集成 @@ -51,16 +71,6 @@ import { CardGrid, LinkCard } from '@astrojs/starlight/components'; title="FeelBack" description="在文档页面中添加用户反馈系统。" /> - - +