🐛 fix plugins.md formatting for docs with dockerized docs validation #1722

marcellodesales · 2025-01-03T05:08:40Z

Can't build the docs because of the following:

docs/docs/packages/plugins.md

So, I'm adding the following features:

Dockerized support of the docusaurus dir docs
- Locally builds with pnpm cache in docker
- Fail builds by the typescript linting of the docs, helping developers to quickly iterate over them
- Runs a server locally so that developers can verify the docs locally before sending PRs

Relates to:

Serve docusaurus docs from a docker container for quick docs verification #1720

Risks

Low: new code added

Background

Docs can be added with errors
Dependencies are missing, causing errors for developers to locally verify the docs
Linting of docs could be added for free when containerizing the build

What does this PR do?

Fixes the build of the docs
Fixes the existing linting error in the docs

What kind of change is this?

Bug fixes (non-breaking change which fixes an issue)

Why are we doing this? Any context or related work?

Or else we can't build the docs locally

Documentation changes needed?

Added a section to the docs/README.md file.

Testing

Running the dockerized docs build will fail with the main branch:

    39.56 [webpackbar] ✔ Client: Compiled with some errors in 37.40s
    39.56 [ERROR] Client bundle compiled with errors therefore further build is impossible.
    39.56 Error: MDX compilation failed for file "/opt/docusaurus/docs/packages/plugins.md"
    39.56 Cause: Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc
    39.56 Details:
    39.56 {
    39.56   "column": 1,
    39.56   "message": "Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc",
    39.56   "line": 617,
    39.56   "name": "617:1",
    39.56   "place": {
    39.56     "_bufferIndex": 0,
    39.56     "_index": 10,
    39.56     "line": 617,
    39.56     "column": 1,
    39.56     "offset": 21207
    39.56   },
    39.56   "reason": "Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc",
    39.56   "ruleId": "unexpected-lazy",
    39.56   "source": "micromark-extension-mdx-expression",
    39.56   "url": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#unexpected-lazy-line-in-expression-in-container-expected-line-to-be-prefixed"
    39.56 }
    39.56
    39.56 --------------------------

The fix for this document failure was added to 34f23dc and fixed the docs build.

$ git add -p docs/docs/packages/plugins.md
diff --git a/docs/docs/packages/plugins.md b/docs/docs/packages/plugins.md
index 8e13cf70..50e01a84 100644
--- a/docs/docs/packages/plugins.md
+++ b/docs/docs/packages/plugins.md
@@ -610,12 +610,12 @@ The Fuel plugin provides an interface to the Fuel Ignition blockchain.
 **Actions:**

 1. `TRANSFER_FUEL_ETH` - Transfer ETH to a given Fuel address. - **Inputs**: - `toAddress` (string): The Fuel address to transfer ETH to. - `amount` (string): The amount of ETH to transfer. - **Outputs**: Confirmation message with transaction details. - **Example**:
-   `json
-{
+   ```json
+   {
     "toAddress": "0x8F8afB12402C9a4bD9678Bec363E51360142f8443FB171655eEd55dB298828D1",
     "amount": "0.00001"
-}
-`
+   }
+   ```
    **Setup and Configuration:**

 1. **Configure the Plugin**

Screenshots

$ curl -i localhost:3000/eliza/
HTTP/1.1 200 OK
Content-Length: 11470
Content-Disposition: inline; filename="index.html"
Accept-Ranges: bytes
Last-Modified: Fri, 03 Jan 2025 04:54:07 GMT
Content-Type: text/html; charset=utf-8
Date: Fri, 03 Jan 2025 04:56:41 GMT
Connection: keep-alive
Keep-Alive: timeout=5

<!doctype html>
<html lang="en" dir="ltr" class="plugin-pages plugin-id-default" data-has-hydrated="false">
<head>
<meta charset="UTF-8">
<meta name="generator" content="Docusaurus v3.6.3">
<title data-rh="true">eliza | eliza</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://elizaos.github.io/eliza/"><meta data-rh="true" property="og:locale" content="en"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docusaurus_

Before

docker compose -f docker-compose-docs.yaml up --build
[+] Building 59.4s (20/20) FINISHED                                                                                                                      docker:desktop-linux
 => [docs internal] load build definition from Dockerfile.docs                                                                                                           0.0s
 => => transferring dockerfile: 1.88kB                                                                                                                                   0.0s
 => [docs] resolve image config for docker.io/docker/dockerfile:1                                                                                                        1.9s
 => CACHED [docs] docker-image://docker.io/docker/dockerfile:1@sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25                                   0.0s
 => [docs internal] load build definition from Dockerfile.docs                                                                                                           0.0s
 => [docs internal] load metadata for docker.io/library/node:23.3.0-slim                                                                                                 1.3s
 => [docs internal] load .dockerignore                                                                                                                                   0.0s
 => => transferring context: 2B                                                                                                                                          0.0s
 => [docs base 1/4] FROM docker.io/library/node:23.3.0-slim@sha256:8b30809f66a6ea8896b9a5d004b4fe2cc0e8061d981d3784fb0e80a19b86ab9d                                      0.0s
 => [docs internal] load build context                                                                                                                                   0.1s
 => => transferring context: 417.28kB                                                                                                                                    0.1s
 => CACHED [docs base 2/4] RUN corepack enable                                                                                                                           0.0s
 => CACHED [docs base 3/4] WORKDIR /opt/docusaurus                                                                                                                       0.0s
 => CACHED [docs base 4/4] RUN apt-get update && apt-get install -y git                                                                                                  0.0s
 => CACHED [docs prod 1/8] WORKDIR /opt/docusaurus                                                                                                                       0.0s
 => CACHED [docs prod 2/8] COPY docs/package.json /opt/docusaurus/package.json                                                                                           0.0s
 => CACHED [docs prod 3/8] COPY docs/package-lock.json /opt/docusaurus/package-lock.json                                                                                 0.0s
 => CACHED [docs prod 4/8] RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install                                                                                0.0s
 => CACHED [docs prod 5/8] COPY docs/ /opt/docusaurus/                                                                                                                   0.0s
 => CACHED [docs prod 6/8] COPY packages/ /opt/packages/                                                                                                                 0.0s
 => [docs prod 7/8] COPY .git/ /opt/.git/                                                                                                                                0.1s
 => [docs prod 8/8] RUN pnpm run build      
    39.56 [webpackbar] ✔ Client: Compiled with some errors in 37.40s
    39.56 [ERROR] Client bundle compiled with errors therefore further build is impossible.
    39.56 Error: MDX compilation failed for file "/opt/docusaurus/docs/packages/plugins.md"
    39.56 Cause: Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc
    39.56 Details:
    39.56 {
    39.56   "column": 1,
    39.56   "message": "Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc",
    39.56   "line": 617,
    39.56   "name": "617:1",
    39.56   "place": {
    39.56     "_bufferIndex": 0,
    39.56     "_index": 10,
    39.56     "line": 617,
    39.56     "column": 1,
    39.56     "offset": 21207
    39.56   },
    39.56   "reason": "Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc",
    39.56   "ruleId": "unexpected-lazy",
    39.56   "source": "micromark-extension-mdx-expression",
    39.56   "url": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#unexpected-lazy-line-in-expression-in-container-expected-line-to-be-prefixed"
    39.56 }
    39.56
    39.56 --------------------------

After

docker compose -f docker-compose-docs.yaml up --build
[+] Building 59.4s (20/20) FINISHED                                                                                                                      docker:desktop-linux
 => [docs internal] load build definition from Dockerfile.docs                                                                                                           0.0s
 => => transferring dockerfile: 1.88kB                                                                                                                                   0.0s
 => [docs] resolve image config for docker.io/docker/dockerfile:1                                                                                                        1.9s
 => CACHED [docs] docker-image://docker.io/docker/dockerfile:1@sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25                                   0.0s
 => [docs internal] load build definition from Dockerfile.docs                                                                                                           0.0s
 => [docs internal] load metadata for docker.io/library/node:23.3.0-slim                                                                                                 1.3s
 => [docs internal] load .dockerignore                                                                                                                                   0.0s
 => => transferring context: 2B                                                                                                                                          0.0s
 => [docs base 1/4] FROM docker.io/library/node:23.3.0-slim@sha256:8b30809f66a6ea8896b9a5d004b4fe2cc0e8061d981d3784fb0e80a19b86ab9d                                      0.0s
 => [docs internal] load build context                                                                                                                                   0.1s
 => => transferring context: 417.28kB                                                                                                                                    0.1s
 => CACHED [docs base 2/4] RUN corepack enable                                                                                                                           0.0s
 => CACHED [docs base 3/4] WORKDIR /opt/docusaurus                                                                                                                       0.0s
 => CACHED [docs base 4/4] RUN apt-get update && apt-get install -y git                                                                                                  0.0s
 => CACHED [docs prod 1/8] WORKDIR /opt/docusaurus                                                                                                                       0.0s
 => CACHED [docs prod 2/8] COPY docs/package.json /opt/docusaurus/package.json                                                                                           0.0s
 => CACHED [docs prod 3/8] COPY docs/package-lock.json /opt/docusaurus/package-lock.json                                                                                 0.0s
 => CACHED [docs prod 4/8] RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install                                                                                0.0s
 => CACHED [docs prod 5/8] COPY docs/ /opt/docusaurus/                                                                                                                   0.0s
 => CACHED [docs prod 6/8] COPY packages/ /opt/packages/                                                                                                                 0.0s
 => [docs prod 7/8] COPY .git/ /opt/.git/                                                                                                                                0.1s
 => [docs prod 8/8] RUN pnpm run build                                                                                                                                  55.2s
 => [docs] exporting to image                                                                                                                                            0.9s
 => => exporting layers                                                                                                                                                  0.9s
 => => writing image sha256:e8b63482726ab02d720c5cbc116b598909adc1d9affaeb0e56b069683b8a95ea                                                                             0.0s
 => => naming to docker.io/library/eliza-docs                                                                                                                            0.0s
[+] Running 1/0
 ✔ Container eliza-docs-1  Recreated                                                                                                                                     0.1s
Attaching to docs-1
docs-1  | (node:1) ExperimentalWarning: CommonJS module /usr/local/lib/node_modules/npm/node_modules/debug/src/node.js is loading ES Module /usr/local/lib/node_modules/npm/node_modules/supports-color/index.js using require().
docs-1  | Support for loading ES Module in require() is an experimental feature and might change at any time
docs-1  | (Use `node --trace-warnings ...` to show where the warning was created)
docs-1  |
docs-1  | > eliza-docs@0.1.7-alpha.2 serve
docs-1  | > docusaurus serve --host 0.0.0.0 --no-open
docs-1  |
docs-1  | [SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/eliza/

Database changes

None

Deployment instructions

$ docker compose -f docker-compose-docs.yaml up --build

Discord username

@x.crypt0.surf3r

Since the docs dependend on the files from packages, we have to include the Dockerfile.docs in the root directory because of the build context. Adding a new docker-compose-docs.yaml to always build the docs from the file directly. Just adding a new service for the docs: $ docker compose up --build [+] Building 55.5s (20/20) FINISHED docker:desktop-linux => [docs internal] load build definition from Dockerfile.docs 0.0s => => transferring dockerfile: 1.88kB 0.0s => [docs] resolve image config for docker.io/docker/dockerfile:1 1.7s => CACHED [docs] docker-image://docker.io/docker/dockerfile:1@sha256:93bfd3b68c109427185cd78b4779fc82b484b0b7618e36d0f104d4d801e66d25 0.0s => [docs internal] load build definition from Dockerfile.docs 0.0s => [docs internal] load metadata for docker.io/library/node:23.3.0-slim 1.3s => [docs internal] load .dockerignore 0.0s => => transferring context: 2B 0.0s => [docs base 1/4] FROM docker.io/library/node:23.3.0-slim@sha256:8b30809f66a6ea8896b9a5d004b4fe2cc0e8061d981d3784fb0e80a19b86ab9d 0.0s => [docs internal] load build context 0.1s => => transferring context: 409.46kB 0.1s => CACHED [docs base 2/4] RUN corepack enable 0.0s => CACHED [docs base 3/4] WORKDIR /opt/docusaurus 0.0s => CACHED [docs base 4/4] RUN apt-get update && apt-get install -y git 0.0s => CACHED [docs prod 1/8] WORKDIR /opt/docusaurus 0.0s => CACHED [docs prod 2/8] COPY docs/package.json /opt/docusaurus/package.json 0.0s => CACHED [docs prod 3/8] COPY docs/package-lock.json /opt/docusaurus/package-lock.json 0.0s => CACHED [docs prod 4/8] RUN --mount=type=cache,id=pnpm,target=/pnpm/store pnpm install 0.0s => CACHED [docs prod 5/8] COPY docs/ /opt/docusaurus/ 0.0s => CACHED [docs prod 6/8] COPY packages/ /opt/packages/ 0.0s => [docs prod 7/8] COPY .git/ /opt/.git/ 0.1s => [docs prod 8/8] RUN pnpm run build 51.4s => [docs] exporting to image 0.8s => => exporting layers 0.8s => => writing image sha256:0a580f2889191121880df85b8951563386f838f7e5f8723dec750ce292334498 0.0s => => naming to docker.io/library/eliza-docs 0.0s [+] Running 1/0 ✔ Container eliza-docs-1 Recreated 0.0s Attaching to docs-1 docs-1 | (node:1) ExperimentalWarning: CommonJS module /usr/local/lib/node_modules/npm/node_modules/debug/src/node.js is loading ES Module /usr/local/lib/node_modules/npm/node_modules/supports-color/index.js using require(). docs-1 | Support for loading ES Module in require() is an experimental feature and might change at any time docs-1 | (Use `node --trace-warnings ...` to show where the warning was created) docs-1 | docs-1 | > eliza-docs@0.1.7-alpha.2 serve docs-1 | > docusaurus serve --host 0.0.0.0 --no-open docs-1 | docs-1 | [SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/eliza/

While trying to build within a docker image, here are the missing packages. 40.12 40.12 -------------------------- 40.12 40.12 Module not found: Error: Can't resolve 'lunr' in '/opt/docusaurus/.docusaurus' 40.12 40.12 -------------------------- 40.12 40.12 Module not found: Error: Can't resolve '@docusaurus/theme-common' in '/opt/docusaurus/community/components' 40.18 ELIFECYCLE Command failed with exit code 1. ------ failed to solve: process "/bin/sh -c pnpm run build" did not complete successfully: exit code: 1

> [prod 3/4] RUN pnpm ci: 0.645 /usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22090 0.645 throw new UsageError(`No version specified for ${raw2} in "packageManager" of ${source}`); 0.645 ^ 0.645 0.645 UsageError: No version specified for pnpm in "packageManager" of package.json 0.645 at parseSpec (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22090:13) 0.645 at loadSpec (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22164:11) 0.645 at async Engine.findProjectSpec (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22354:22) 0.645 at async Engine.executePackageManagerRequest (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:22410:24) 0.645 at async Object.runMain (/usr/local/lib/node_modules/corepack/dist/lib/corepack.cjs:23102:5) { 0.645 clipanion: { type: 'usage' } 0.645 }

Can't build the docs because of the following: docs/docs/packages/plugins.md 39.56 [webpackbar] ✔ Client: Compiled with some errors in 37.40s 39.56 [ERROR] Client bundle compiled with errors therefore further build is impossible. 39.56 Error: MDX compilation failed for file "/opt/docusaurus/docs/packages/plugins.md" 39.56 Cause: Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc 39.56 Details: 39.56 { 39.56 "column": 1, 39.56 "message": "Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc", 39.56 "line": 617, 39.56 "name": "617:1", 39.56 "place": { 39.56 "_bufferIndex": 0, 39.56 "_index": 10, 39.56 "line": 617, 39.56 "column": 1, 39.56 "offset": 21207 39.56 }, 39.56 "reason": "Unexpected lazy line in expression in container, expected line to be prefixed with `>` when in a block quote, whitespace when in a list, etc", 39.56 "ruleId": "unexpected-lazy", 39.56 "source": "micromark-extension-mdx-expression", 39.56 "url": "https://github.com/micromark/micromark-extension-mdx-expression/tree/main/packages/micromark-extension-mdx-expression#unexpected-lazy-line-in-expression-in-container-expected-line-to-be-prefixed" 39.56 } 39.56 39.56 --------------------------

madjin

yeah that plugins.md typo tripped me up too, I was able to detect it on my system and fix. I think these changes would be good for CI, especially as we get into more agentic documentation practices.

marcellodesales · 2025-01-04T01:39:09Z

Thank you @madjin... I'm glad it worked and you also found it!!!

I can add a github actions to perform CI/CD with a dockerized version of it! That way we can lint the docs before publishing the latest... I will take a look at the current github actions from the repo and extend it...

thank you!

marcellodesales · 2025-01-04T01:59:28Z

@madjin I see the merged PR is shown a broken check...

I see this error about the Node version in the chores CI https://github.com/elizaOS/eliza/actions/runs/12606089734/job/35135742899#step:5:8
The package.json settings was updated last week at https://github.com/elizaOS/eliza/blame/develop/docs/package.json#L56
Maybe we can just add the current version from CI... Since we use github actions to setup, we need to update it to a wider version of node...

"engines": {
    "node": ">=23.3.0 <24"
}

I do see also that I missed the frozen pnpm-lock.yaml... I can add that as well...
Finally, I think this chore CI could be included in the PRs so that contributors can validate for this broader area of the docs...

…ed-docs-support 🐛 fix plugins.md formatting for docs with dockerized docs validation

marcellodesales changed the title ~~🐛 fix plugins.md formatting for docs~~ 🐛 fix plugins.md formatting for docs with dockerized docs validation Jan 3, 2025

marcellodesales added 5 commits January 2, 2025 21:12

📚 add section to docs/README.md for dockerized docs

6f77bf0

marcellodesales force-pushed the feature/dockerized-docs-support branch from 5ba2902 to bf4d5d0 Compare January 3, 2025 05:12

marcellodesales added 2 commits January 3, 2025 05:14

Merge branch 'develop' into feature/dockerized-docs-support

b44ccb3

Merge branch 'develop' into feature/dockerized-docs-support

555dc24

marcellodesales mentioned this pull request Jan 3, 2025

Serve docusaurus docs from a docker container for quick docs verification #1720

Closed

madjin added documentation Improvements or additions to documentation enhancement New feature or request labels Jan 4, 2025

Merge branch 'develop' into feature/dockerized-docs-support

790e6e1

madjin approved these changes Jan 4, 2025

View reviewed changes

madjin merged commit ee79ef2 into elizaOS:develop Jan 4, 2025
3 checks passed

marcellodesales deleted the feature/dockerized-docs-support branch January 4, 2025 01:37

odilitime mentioned this pull request Jan 4, 2025

chore: Develop => main for 1.7.0 release #1717

Merged

1to3for5vi7ate9x pushed a commit to 1to3for5vi7ate9x/eliza that referenced this pull request Jan 26, 2025

Merge pull request elizaOS#1722 from marcellodesales/feature/dockeriz…

78631d9

…ed-docs-support 🐛 fix plugins.md formatting for docs with dockerized docs validation

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🐛 fix plugins.md formatting for docs with dockerized docs validation #1722

🐛 fix plugins.md formatting for docs with dockerized docs validation #1722

marcellodesales commented Jan 3, 2025 •

edited

Loading

madjin left a comment

marcellodesales commented Jan 4, 2025

marcellodesales commented Jan 4, 2025 •

edited

Loading

🐛 fix plugins.md formatting for docs with dockerized docs validation #1722

🐛 fix plugins.md formatting for docs with dockerized docs validation #1722

Conversation

marcellodesales commented Jan 3, 2025 • edited Loading

Relates to:

Risks

Background

What does this PR do?

What kind of change is this?

Why are we doing this? Any context or related work?

Documentation changes needed?

Testing

Screenshots

Before

After

Database changes

Deployment instructions

Discord username

madjin left a comment

Choose a reason for hiding this comment

marcellodesales commented Jan 4, 2025

marcellodesales commented Jan 4, 2025 • edited Loading

marcellodesales commented Jan 3, 2025 •

edited

Loading

marcellodesales commented Jan 4, 2025 •

edited

Loading