Sepolia content population

.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 }}

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
 

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.

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,
         {

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<string, [string, string][]> = {
+  "~/components/Aside.astro": [["default", AsideTagname]],
+}
 /**
  * remark plugin that converts blocks delimited with `:::` into instances of
  * the `<Aside>` component. Depends on the `remark-directive` module for the
@@ -38,8 +36,9 @@ function remarkAsides(): unified.Plugin<[], mdast.Root> {
   const variants = new Set(["note", "tip", "caution", "danger"])
 
   const transformer: unified.Transformer<mdast.Root> = (tree) => {
-    visit(tree, (node) => {
-      if (node.type !== "containerDirective") return
+    // @ts-expect-error Possibly infinite type instantiation we can’t do anything about.
+    visit(tree, (node, index, parent) => {
+      if (!parent || index === null || node.type !== "containerDirective") return
       const type = node.name
       if (!variants.has(type)) return
 
@@ -57,9 +56,8 @@ function remarkAsides(): unified.Plugin<[], mdast.Root> {
         }
       })
 
-      const data = node.data || (node.data = {})
-      data.hName = AsideTagname
-      data.hProperties = h(AsideTagname, { type, title }).properties
+      // Replace this node with the aside component it represents.
+      parent.children[index] = makeComponentNode(AsideTagname, { attributes: { type, title } }, ...node.children)
     })
   }
 
@@ -75,18 +73,12 @@ export function astroCallouts(): AstroIntegration {
   return {
     name: "@astrojs/callouts",
     hooks: {
-      "astro:config:setup": ({ injectScript, updateConfig }) => {
+      "astro:config:setup": ({ updateConfig }) => {
         updateConfig({
           markdown: {
             remarkPlugins: [remarkDirective, remarkAsides()],
           },
         })
-
-        // Auto-import the Aside component and attach it to the global scope
-        injectScript(
-          "page-ssr",
-          `import ${AsideTagname} from "~/components/Aside.astro"; global.${AsideTagname} = ${AsideTagname};`
-        )
       },
     },
   }

integrations/solidity-remix.ts

@@ -10,9 +10,14 @@ import { h } from "hastscript"
 import remarkDirective from "remark-directive"
 import { visit } from "unist-util-visit"
 import { remove } from "unist-util-remove"
+import { makeComponentNode } from "./utils/makeComponentNode"
 
 const CodeSampleTagName = "AutoImportedCodeSample"
 
+export const codeSampleAutoImport: Record<string, [string, string][]> = {
+  "~/components/CodeSample/CodeSample.astro": [["default", CodeSampleTagName]],
+}
+
 /**
  * remark plugin that converts blocks delimited with `:::` into instances of
  * the `<CodeSample>` component. Depends on the `remark-directive` module for the
@@ -52,6 +57,18 @@ function remarkSolidityRemix(): unified.Plugin<[], mdast.Root> {
 
       if (!src) throw Error("No source was provided for the solidity example")
 
+      // const codeSnippetWrapper = makeComponentNode(
+      // 	CodeSnippetTagname,
+      // 	{ mdx: isMDX, attributes },
+      // 	code
+      // );
+
+      // parent.children[index] = makeComponentNode(
+      // 	AsideTagname,
+      // 	{ mdx: isMDXFile(file), attributes: { type, title } },
+      // 	...node.children
+      // );
+
       const data = node.data || (node.data = {})
       data.hName = CodeSampleTagName
       data.hProperties = h(CodeSampleTagName, {
@@ -73,18 +90,12 @@ export function solidityRemixCode(): AstroIntegration {
   return {
     name: "@smart-contract/solidity-remix",
     hooks: {
-      "astro:config:setup": ({ injectScript, updateConfig }) => {
+      "astro:config:setup": ({ updateConfig }) => {
         updateConfig({
           markdown: {
             remarkPlugins: [remarkDirective, remarkSolidityRemix()],
           },
         })
-
-        // Auto-import the Aside component and attach it to the global scope
-        injectScript(
-          "page-ssr",
-          `import ${CodeSampleTagName} from "~/components/CodeSample/CodeSample.astro"; global.${CodeSampleTagName} = ${CodeSampleTagName};`
-        )
       },
     },
   }

integrations/utils/makeComponentNode.ts

@@ -0,0 +1,33 @@
+import type { BlockContent } from "mdast"
+import type { MdxJsxAttribute, MdxJsxFlowElement } from "mdast-util-mdx-jsx"
+
+interface NodeProps {
+  attributes?: Record<string, string | boolean | number | undefined | null>
+}
+
+/**
+ * Create AST node for a custom component injection.
+ *
+ * @example
+ * makeComponentNode('MyComponent', { prop: 'val' }, h('p', 'Paragraph inside component'))
+ *
+ */
+export function makeComponentNode(
+  name: string,
+  { attributes = {} }: NodeProps = {},
+  ...children: BlockContent[]
+): MdxJsxFlowElement {
+  return {
+    type: "mdxJsxFlowElement",
+    name,
+    attributes: Object.entries(attributes)
+      // Filter out non-truthy attributes to avoid empty attrs being parsed as `true`.
+      .filter(([_k, v]) => v !== false && Boolean(v))
+      .map(([name, value]) => ({
+        type: "mdxJsxAttribute",
+        name,
+        value: value as MdxJsxAttribute["value"],
+      })),
+    children,
+  }
+}