diff --git a/.github/workflows/update-algolia-index.yml b/.github/workflows/update-algolia-index.yml index 2106bd47b..244dec054 100644 --- a/.github/workflows/update-algolia-index.yml +++ b/.github/workflows/update-algolia-index.yml @@ -5,7 +5,28 @@ on: [push] jobs: update-prod-index: if: ${{ github.ref == 'refs/heads/main' }} - name: Update algolia index + name: Update algolia index -- Prod + runs-on: ubuntu-latest + env: + ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }} + ALGOLIA_WRITE_API_KEY: ${{ secrets.ALGOLIA_WRITE_API_KEY }} + ALGOLIA_INDEX_NAME: prod_scroll-docs + defaults: + run: + working-directory: ./ + steps: + - name: Checkout Repo + uses: actions/checkout@v3 + - name: Install Dependencies + run: npm i + - name: Build + run: npm run build + - name: Update index + run: npm run update-algolia-index + + update-dev-index: + if: ${{ github.ref == 'refs/heads/develop' || github.ref == 'refs/heads/sepolia-content-population' }} + name: Update algolia index -- Dev runs-on: ubuntu-latest env: ALGOLIA_APP_ID: ${{ secrets.ALGOLIA_APP_ID }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 21a586423..2f8d6154c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,20 +1,26 @@ # Contributing to the Scroll Documentation -PRs are welcome! We try to keep a clean commit history, so we'll follow a standard process initially created by the Chainlink team whose documentation we forked: +As we build out the initial scope of the documentation, we intend to be selective about PRs, especially in our English language documentation. If you're interested in making a code or content contribution, please start by creating an issue and discussing the idea with a member of our team. -- Create a PR +If you want information about contributing a translation, please see [TRANSLATION.md](./TRANSLATION.md). + +We try to keep a clean commit history, so we'll follow a standard process initially created by the Chainlink team whose documentation we forked: + +- Create a new issue + - Comment on the issue if you'd like to be assigned to it +- Fork the Repo & Create a PR - If your PR contains multiple commits, we'll ask you to squash them - - If your PR has conflicts with `main`, we'll ask you to rebase it + - If your PR has conflicts with `develop`, we'll ask you to rebase it - Someone will review your PR - Your PR will be merged, amended, closed, or you'll be asked for changes ## Standards - Commit messages - - Start with a present tense verb + - Start with a present-tense verb - Keep your commit headline short but sufficient to understand the scope and focus of the change. - Changes are often formatted like `add doc X`, `fix page Y`, `improve docs for Z`. - - Example: "`update contract addresses for BSC`". + - Example: "`update contract addresses for USDC on Scroll Sepolia`". - If you touch any infrastructure, make sure it builds with `yarn build` - Trust the autoformatter (prettier) - Make sure images are optimized and compressed @@ -29,7 +35,7 @@ git rebase origin/main git push -f ``` -It's okay to force push over your own PR branch. In fact, that's what we want so that the commits are clean. +It's okay to force push over your own PR branch. That's what we want so that the commits are clean. ## How to squash a PR diff --git a/TRANSLATION.md b/TRANSLATION.md new file mode 100644 index 000000000..82f32bfb3 --- /dev/null +++ b/TRANSLATION.md @@ -0,0 +1,26 @@ +# Translation Initiative + +_Our translation initiative hopes to translate Scroll documentation into different languages and make the website accessible to people worldwide._ + +Our current documentation is only available in English, but with community contributions, we want to support many language communities. Since this is a new initiative and we want to maintain high assurances about the information in our documentation, **we're only accepting contributions in Mandarin and Spanish**. Once we're comfortable with the process and can ensure a good experience for community translators, we'll seek contributions in additional languages. + +### Want to get involved as a translator? + +Create an issue describing which article you wish to translate. Then get started! If you need help or have any questions, join the [Scroll Discord](https://discord.gg/scroll). Once your translation is submitted, we'll ask a member of our team to do a review. + +### Standards and Policies + +For now, we will defer to Ethereum.org's excellent [Translation Style Guide](https://ethereum.org/en/contributing/translation-program/translators-guide/). We do not use a translation platform, but please assume all other guidance applies here. + +## Starting a translation + +1. Fork this repository +1. Create an issue named using the format "Translation: _[English Article Name]_ (_[lang]_)" -- for example, "Translation: User Guide Faucet (zh)" +1. Find the article you wish to translate in `src/content/docs/en/` and copy it to a matching folder in `src/content/docs/[lang]/`. All files should maintain the same file name and folder structure as the English version of the site. +1. To translate UI elements or article names, modify the appropriate entry in `public/locales/[lang]/translation.json`. If you're unsure what to do here, suggest any additional changes to the site in your PR. +1. Make a PR with the title following the template above. Be sure to mention the original issue in your description. +1. A team member will review, recommend changes and work with you to get the final version added to the code base. + +### Not familiar with Git? + +If you don't want to worry about all this Git stuff, contact a team member or community moderator on the [Scroll Discord](https://discord.gg/scroll). We'd be happy to point you at the original file to translate and suggest an online text editor (like [HackMD](https://hackmd.io/)) for sharing your results. We'll take it from there. diff --git a/astro.config.ts b/astro.config.ts index dda7ba0f8..94d241367 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -2,16 +2,18 @@ import { defineConfig } from "astro/config" import preact from "@astrojs/preact" import react from "@astrojs/react" import astroI18next from "astro-i18next" -import { astroCallouts } from "./integrations/astro-callouts" -import { solidityRemixCode } from "./integrations/solidity-remix" +import { astroCallouts, asideAutoImport } from "./integrations/astro-callouts" +import { solidityRemixCode, codeSampleAutoImport } from "./integrations/solidity-remix" import { youtubeEmbed } from "./integrations/youtube-embed" import mdx from "@astrojs/mdx" import rehypeSlug from "rehype-slug" import rehypeAutolinkHeadings from "rehype-autolink-headings" import rehypeKatex from "rehype-katex" +import rehypeMermaid from "rehype-mermaidjs" import remarkGfm from "remark-gfm" import remarkMath from "remark-math" import image from "@astrojs/image" +import AutoImport from "astro-auto-import" import sitemap from "@astrojs/sitemap" @@ -24,6 +26,9 @@ export default defineConfig({ astroFlavoredMarkdown: true, }, integrations: [ + AutoImport({ + imports: [asideAutoImport, codeSampleAutoImport], + }), preact({ compat: true, }), @@ -47,6 +52,7 @@ export default defineConfig({ remarkPlugins: [remarkMath, remarkGfm], rehypePlugins: [ rehypeSlug, + [rehypeMermaid, { strategy: "img-png" }], [ rehypeAutolinkHeadings, { diff --git a/integrations/astro-callouts.ts b/integrations/astro-callouts.ts index b02f729dd..e39507891 100644 --- a/integrations/astro-callouts.ts +++ b/integrations/astro-callouts.ts @@ -1,18 +1,16 @@ -/** - * Astro's implementation of callouts - * https://github.com/withastro/docs/blob/main/integrations/astro-asides.ts - */ - import type { AstroIntegration } from "astro" import type * as mdast from "mdast" -import type * as unified from "unified" -import { h } from "hastscript" import remarkDirective from "remark-directive" -import { visit } from "unist-util-visit" +import type * as unified from "unified" import { remove } from "unist-util-remove" +import { visit } from "unist-util-visit" +import { makeComponentNode } from "./utils/makeComponentNode" const AsideTagname = "AutoImportedAside" +export const asideAutoImport: Record = { + "~/components/Aside.astro": [["default", AsideTagname]], +} /** * remark plugin that converts blocks delimited with `:::` into instances of * the `