feat(docs): Add block documentation auto-generation system #11707
Conversation
- Add generate_block_docs.py script that introspects block code to generate markdown - Support manual content preservation via <!-- MANUAL: --> markers - Add migrate_block_docs.py to preserve existing manual content from git HEAD - Add CI workflow (docs-block-sync.yml) to fail if docs drift from code - Add Claude PR review workflow (docs-claude-review.yml) for doc changes - Add manual LLM enhancement workflow (docs-enhance.yml) - Add GitBook configuration (.gitbook.yaml, SUMMARY.md) - Fix non-deterministic category ordering (categories is a set) - Add comprehensive test suite (32 tests) - Generate docs for 444 blocks with 66 preserved manual sections 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
ntindle
requested review from
Bentlybro and
kcze
and removed request for
a team
github-project-automation
bot
moved this to 🆕 Needs initial review
in AutoGPT development kanban
github-actions
bot
added
documentation
WalkthroughAdds automated doc tooling and workflows: GitHub Actions for docs sync/check/review/enhance, CLI scripts to generate and migrate per-block Markdown from code introspection, tests for the generator, many new/updated block documentation files, and small block description text updates in backend block classes. Changes
Sequence Diagram(s)sequenceDiagram
participant PR as Pull Request / Push
participant GH as GitHub Actions
participant Runner as Actions Runner (ubuntu)
participant Repo as Repository (checkout)
participant Python as generate_block_docs.py / migrate script
participant Claude as Claude Code Action (anthropics)
participant Git as Git CLI / GitHub API
PR->>GH: trigger (push / pull_request / workflow_dispatch)
GH->>Runner: start job
Runner->>Repo: checkout code
Runner->>Python: run generate_block_docs.py --check
Python-->>Runner: exit 0 / non-zero (diffs)
alt docs out-of-sync
Runner->>Git: show git diff (docs)
Runner-->>GH: job fails (report)
else docs in-sync
Runner-->>GH: job succeeds
end
%% Enhance / Claude review flow (manual or PR)
PR->>GH: trigger Claude review / enhance
GH->>Runner: start claude job
Runner->>Repo: checkout full history
Runner->>Claude: send PR diff and doc files (with prompt)
Claude-->>Runner: review comments or enhanced content
alt enhance live
Runner->>Git: create branch, commit changes, open PR
else dry-run
Runner-->>GH: post proposed changes in logs
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Suggested labels
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing touches
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
PR Reviewer Guide 🔍Here are some key observations to aid the review process:
|
|
Thank you for submitting this PR that adds a block documentation auto-generation system! The changes look well-structured and comprehensive, including scripts for doc generation, migration tools, and CI workflows to keep docs in sync with code. However, I cannot approve this PR yet because:
Before this can be merged, please:
The changes themselves look good and match the intent described in the PR title. Once you've completed the checklist, this should be ready for another review. |
|
Thank you for creating this documentation auto-generation system. This will help keep block documentation consistent and up-to-date. Before this can be merged, please address the following:
The implementation itself looks well-designed with features to:
Once you've completed the checklist and enhanced the description with workflow information, this PR should be ready for review. |
|
Thank you for the comprehensive PR implementing a block documentation auto-generation system! This will be very valuable for maintaining accurate and consistent documentation. Before we can merge this PR, there are a couple of items that need to be addressed:
The code changes themselves look excellent:
Once you complete the checklist and add a test plan, this PR will be ready for merging. |
There was a problem hiding this comment.
Pull request overview
This PR introduces a comprehensive block documentation auto-generation system for the AutoGPT platform. The system introspects block code to automatically generate markdown documentation, supports manual content preservation via special markers, and includes CI workflows to ensure documentation stays in sync with code.
- Auto-generation system: Scripts to generate and migrate block documentation from code
- CI integration: Workflows to detect documentation drift and enable automated reviews
- Comprehensive coverage: Documentation generated for 444 blocks with 66 preserved manual sections
Reviewed changes
Copilot reviewed 132 out of 132 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/content/platform/blocks/twitter/blocks.md | Documentation for Twitter blocked users functionality |
| docs/content/platform/blocks/twitter/*.md | Multiple Twitter API integration block documentation files |
| docs/content/platform/blocks/todoist/*.md | Todoist task management block documentation |
| docs/content/platform/blocks/text.md | Text manipulation and processing block documentation |
| docs/content/platform/blocks/stagehand/blocks.md | Stagehand web automation block documentation |
| docs/content/platform/blocks/search.md | Web search and Wikipedia integration documentation |
| docs/content/platform/blocks/llm.md | Large Language Model and AI block documentation |
| docs/content/platform/blocks/logic.md | Logic and data manipulation block documentation |
| docs/content/platform/blocks/misc.md | Miscellaneous utility block documentation |
| docs/content/platform/blocks/multimedia.md | Media processing block documentation |
| docs/content/platform/blocks/*/*.md | Additional block documentation across various integrations (Linear, Jina, HubSpot, Google Sheets, Notion, Nvidia, Replicate, Slant3D, SmartLead, System, ZeroBounce, Wolfram) |
| Interact with a web page by performing actions on a web page. | ||
|
|
||
| ### What it does | ||
| Interact with a web page by performing actions on a web page. Use it to build self-healing and deterministic automations that adapt to website chang. |
There was a problem hiding this comment.
The description in "What it does" section has a typo: "chang" should be "changes" at the end of the sentence.
| @@ -0,0 +1,38 @@ | |||
| # Twitter Geted Users | |||
There was a problem hiding this comment.
The block title "Twitter Geted Users" contains a spelling error. It should be "Twitter Get Blocked Users" or "Twitter Get Users" depending on the intended functionality.
|
Thank you for this comprehensive PR adding a block documentation auto-generation system! The implementation looks very thorough with good organization and test coverage. However, before we can approve this PR, please complete the checklist in the PR description. Even though this is primarily documentation tooling, the checklist items still need to be checked off since you're adding new code (Python scripts) to the repository. Specifically:
Some suggestions for the test plan might include:
Once you've completed the checklist, we'll be happy to review this again. The actual implementation looks solid! |
|
Thank you for this comprehensive PR that introduces a block documentation auto-generation system. The implementation looks well thought out with scripts, testing, and CI workflows to maintain documentation quality. However, I notice that the PR checklist is incomplete. Before we can merge this PR, please complete the checklist in the PR description by checking off the items:
Please fill out these items, especially adding a test plan that describes how you've verified this documentation system works correctly. Once the checklist is complete, this PR appears ready to merge. The documentation generation system will be very valuable for keeping block documentation in sync with the actual code. |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 24
Note
Due to the large number of review comments, Critical severity comments were prioritized as inline comments.
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/content/platform/blocks/notion/read_page_markdown.md (1)
1-38: Fix markdown formatting violations: heading levels and blank lines around tables.The auto-generated documentation has consistent formatting issues flagged by markdownlint:
- Heading levels (MD001): Top-level section headings use h3 (
###) instead of h2 (##). Lines 3, 6, 9, 14, 20, 27 should use h2 to maintain proper hierarchy after the h1 title.- Table spacing (MD058): Tables need blank lines before and after them (lines 15 and 21).
Since these files are auto-generated, fix the root cause in
generate_block_docs.pyto ensure all 148 generated documentation files conform to markdown standards.🔎 Proposed fixes for this file
-# Notion Read Page Markdown +# Notion Read Page Markdown + -### What it is +## What it is Read a Notion page and convert it to Markdown format with proper formatting for headings, lists, links, and rich text. -### What it does +## What it does Read a Notion page and convert it to Markdown format with proper formatting for headings, lists, links, and rich text. -### How it works +## How it works <!-- MANUAL: how_it_works --> _Add technical explanation here._ <!-- END MANUAL --> -### Inputs +## Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| | page_id | Notion page ID. Must be accessible by the connected integration. You can get this from the page URL notion.so/A-Page-586edd711467478da59fe35e29a1ffab would be 586edd711467478da59fe35e29a1ffab | str | Yes | | include_title | Whether to include the page title as a header in the markdown | bool | No | -### Outputs +## Outputs + | Output | Description | Type | |--------|-------------|------| | error | Error message if the operation failed | str | | markdown | Page content in Markdown format. | str | | title | Page title. | str | -### Possible use case +## Possible use case <!-- MANUAL: use_case --> _Add practical use case examples here._ <!-- END MANUAL -->
🤖 Fix all issues with AI agents
In @docs/content/platform/blocks/ayrshare/post_to_tiktok.md:
- Line 37: The table row is malformed because pipe characters in the type column
aren’t escaped and the docs mention a non-existent 'FRIENDS' visibility; update
the docs generator to escape pipes in the type string (ensure the code that
builds the table row escapes "|" in the variable type_str, e.g., replace "|"
with "\|", before concatenating the row) and reconcile the TikTok visibility
options by either adding FRIENDS to the TikTokVisibility enum in
post_to_tiktok.py or removing 'friends' from the visibility description so the
enum and docs match.
In @docs/content/platform/blocks/enrichlayer/linkedin.md:
- Around line 15-26: The table rows for fallback_to_cache and use_cache are
malformed because their Type cells contain unescaped pipe characters; to fix,
update the two rows (fallback_to_cache and use_cache) so the union types are
rendered as single cell values by escaping the pipe characters or wrapping the
entire Type value in inline code/backticks (e.g., `on-error | never` and
`if-present | never`), ensuring each row has exactly four columns and the table
header aligns correctly.
In @docs/content/platform/blocks/exa/research.md:
- Around line 14-22: The markdown table is broken by unescaped union pipes in
the model type cell and missing surrounding blank lines; update the generator
that emits block docs so the model cell outputs a backticked, comma-separated
list (e.g., `exa-research-fast`, `exa-research`, `exa-research-pro`) instead of
raw pipes, and ensure it inserts a blank line before and after generated tables
(fix the table rendering for the `model` cell and apply same change to other
block files using the same pattern).
- Around line 14-22: Add a blank line immediately before the table so the
markdown linter (MD058) recognizes it as a table, and fix the model type cell
that currently reads "exa-research-fast" | "exa-research" | "exa-research-pro"
by escaping the pipe characters (e.g., replace each | with | or wrap the
entire union in inline code/backticks) so the pipes don’t break the table
columns; update the row labelled "model" in the table under the Inputs section
accordingly.
In @docs/content/platform/blocks/exa/search.md:
- Around line 1-12: The document has markdown validation errors: the top-level
heading jumps from H1 to H3 (MD001), the Inputs table lacks a preceding blank
line (MD058) and its rows incorrectly use pipe characters inside type cells
causing mismatched columns (MD056), plus capitalization issues for
GitHub/LinkedIn. Fix by changing the H3 "What it is" to an H2 (or remove the H1)
to restore proper heading hierarchy, insert a blank line before the "### Inputs"
section, and update the table so type values do not include unescaped pipes—use
comma-separated or backtick-wrapped values (e.g., keyword, neural, fast or
`keyword`, `neural`, `fast`) so the header and rows have the same number of
columns; also normalize "github" and "linkedin" to "GitHub" and "LinkedIn".
In @docs/content/platform/blocks/exa/websets_monitor.md:
- Around line 174-190: The Inputs table’s Type cell for the status row is
malformed because it contains pipe characters ("enabled" | "disabled" |
"paused") which break the Markdown table; fix the Update Monitor Inputs table by
changing the status Type cell to a simple type (e.g., str) and move the allowed
values into the Description (e.g., "New status for the monitor — allowed values:
enabled, disabled, paused") or add a separate Allowed Values column, ensuring no
raw pipe characters remain in any Type cell so the table parses correctly.
In @docs/content/platform/blocks/exa/websets.md:
- Around line 84-106: The markdown table Type column breaks because union pipes
aren't escaped; update generate_block_docs.py so type_str used for table cells
is escaped before insertion (e.g. replace "|" with "\|")—specifically modify
where inp.type_str is written into the table (the block that builds the inputs
table around lines that reference type_str) and do the same for outputs (the
analogous block around the outputs table); ensure type_to_readable() can still
produce unions/enums but escape pipes on the final type_str variable before
formatting into the Markdown table.
In @docs/content/platform/blocks/firecrawl/crawl.md:
- Line 22: The table cell for the "formats" type contains raw pipe characters
which break the Markdown table parser (MD056); update the docs to either escape
each '|' as '\|' or wrap the entire type string in backticks (e.g.,
`List["markdown" \| "html" \| "rawHtml"]`) so the cell stays a single column,
and then modify the documentation generator (generate_block_docs.py) to
automatically escape or backtick any '|' characters in type definitions before
emitting table rows to prevent this across all generated blocks.
In @docs/content/platform/blocks/github/ci.md:
- Line 18: The inputs table row is malformed because the cell `str | int` was
accidentally split into two cells (`str` and `int`), producing five cells for a
four-column table; edit the row that currently reads `| target | Commit SHA or
PR number to get CI results for | str | int | Yes |` and remove the extra pipe
so the third cell contains `str | int` (i.e., `| target | Commit SHA or PR
number to get CI results for | str | int | Yes |` collapsed to four cells),
ensuring the table columns align with the header.
In @docs/content/platform/blocks/github/statuses.md:
- Around line 14-23: Add a blank line immediately before the "Inputs" table and
another blank line after it, and fix the Type column for the state row by
replacing the pipe-separated values with a safe inline description such as: "str
(one of: error, failure, pending)" so the table cell no longer contains raw pipe
characters that break Markdown table parsing; update the row with the "state"
Input label accordingly.
In @docs/content/platform/blocks/smartlead/campaign.md:
- Around line 92-98: The Outputs table row for the "data" output currently
contains an unescaped pipe in the union type "Dict[str, True] | str" which
breaks the Markdown table; update the "data" type cell in the Outputs table so
the pipe is escaped (e.g., `\|`) or the entire type is fenced/inline-code
formatted to prevent the pipe from being treated as a column delimiter, ensuring
the table remains three columns and the "data" row displays correctly.
In @docs/content/platform/blocks/todoist/labels.md:
- Line 19: The table rows for the "color" field (occurrences around the color
field at lines referenced) have extra pipe-separated cells for each enum value
causing MD056; update each row so the table has exactly four columns (Input,
Description, Type, Required) by collapsing the multiple color option cells into
a single Type cell that lists the enum values (e.g.,
enum("berry_red","red","orange") or a comma-separated list) and keep the final
Required cell as "No"; apply the same change to both occurrences (the row around
line 19 and the one around line 241).
In @docs/content/platform/blocks/todoist/projects.md:
- Line 19: The table row for the "color" field currently splits the color
enumeration into multiple cells (e.g. | color | Color of the project icon |
"berry_red" | "red" | "orange" | No |), causing a column count mismatch; fix
both occurrences by collapsing the enumeration into a single cell (for example:
| color | Color of the project icon | "berry_red", "red", "orange" | No |) or by
quoting/backticking the entire list so the row has the correct number of columns
for the table.
In @docs/content/platform/blocks/twitter/list_lookup.md:
- Around line 3-12: Change the subsection headings from H3 (###) to H2 (##) for
the three blocks titled "What it is", "What it does", and "How it works" in
list_lookup.md (and apply the same fix to websets.md and timeline.md); update
the markdown so each subsection uses ## instead of ### and then check and
correct the generation script that emits these files to prevent reintroducing H3
headings in future builds.
In @docs/content/platform/blocks/twitter/pinned_lists.md:
- Around line 14-36: The table cells for the Inputs column contain multi-line
descriptions that break Markdown table parsing; flatten the descriptions for the
expansions, user_fields, and list_fields rows into single-line text (remove
embedded newlines and list bullets, replacing them with commas or
semicolon-separated phrases) so each cell is one continuous line; ensure the
header row and pipe separators remain unchanged and that the cell content for
the symbols "expansions", "user_fields", and "list_fields" becomes a single-line
description each.
- Around line 14-36: The table in pinned_lists.md is broken by literal newlines
in field descriptions; remove newlines from the source description strings so
table cells are single-line. Edit the ListExpansionInputs field definitions in
autogpt_platform/backend/backend/blocks/twitter/_types.py to strip or replace
'\n' characters (e.g., join lines or replace with spaces) for the descriptions
of expansions, user_fields, and list_fields; additionally update
generate_block_docs.py to sanitize/normalize description text (trim, collapse
newlines to spaces, and escape pipes) before emitting markdown so future
generated tables remain single-line cells.
In @docs/content/platform/blocks/twitter/timeline.md:
- Around line 3-12: Change the subsection headings from H3 to H2 in this
document: replace "### What it is", "### What it does" and "### How it works"
with "## What it is", "## What it does" and "## How it works" respectively, and
ensure the same fix is applied programmatically in the content generation script
that produced websets.md so future files use H2 for these subsections.
- Around line 14-36: The markdown table row for the "expansions" input contains
a multi-line bullet list that breaks the table; change that cell to a
single-line description (e.g., "Choose extra info to include (e.g., media keys,
author user ID, place ID); see details below.") or move the detailed bullet list
out of the table into a short subsection under the table, and apply the same fix
to the other problematic rows noted (the repeated expansion descriptions around
lines 79–82 and 137–140) so every table row remains a single line and the table
column count stays consistent.
| | image_cover_index | Index of image to use as cover (0-based, image posts only) | int | No | | ||
| | title | Title for image posts | str | No | | ||
| | thumbnail_offset | Video thumbnail frame offset in milliseconds (video only) | int | No | | ||
| | visibility | Post visibility: 'public', 'private', 'followers', or 'friends' | "public" | "private" | "followers" | No | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's check if the file exists and examine the table structure around line 37
if [ -f "docs/content/platform/blocks/ayrshare/post_to_tiktok.md" ]; then
echo "=== File exists. Showing lines 30-45 with context ==="
sed -n '30,45p' "docs/content/platform/blocks/ayrshare/post_to_tiktok.md"
else
echo "File not found. Searching for it..."
find . -name "*post_to_tiktok*" -type f
fiRepository: Significant-Gravitas/AutoGPT
Length of output: 200
🏁 Script executed:
# Search for generate_block_docs.py
find . -name "generate_block_docs.py" -type fRepository: Significant-Gravitas/AutoGPT
Length of output: 200
🏁 Script executed:
# Also check if there are any other markdown files in the ayrshare directory to see the pattern
fd "post_to_tiktok" . --type fRepository: Significant-Gravitas/AutoGPT
Length of output: 198
🏁 Script executed:
# Read the markdown file around line 37 with context
cat -n "docs/content/platform/blocks/ayrshare/post_to_tiktok.md" | sed -n '30,50p'Repository: Significant-Gravitas/AutoGPT
Length of output: 1904
🏁 Script executed:
# Find generate_block_docs.py
find . -name "generate_block_docs.py" -type f 2>/dev/nullRepository: Significant-Gravitas/AutoGPT
Length of output: 129
🏁 Script executed:
# Also check the Python block file to understand the visibility parameter
cat -n "autogpt_platform/backend/backend/blocks/ayrshare/post_to_tiktok.py" | head -100Repository: Significant-Gravitas/AutoGPT
Length of output: 4873
🏁 Script executed:
# Read the generate_block_docs.py script to understand how it generates tables
cat -n "./autogpt_platform/backend/scripts/generate_block_docs.py" | head -200Repository: Significant-Gravitas/AutoGPT
Length of output: 6987
🏁 Script executed:
# Search for how the script handles enum or union types in table generation
rg -A 10 -B 5 "union|Literal|Enum" "./autogpt_platform/backend/scripts/generate_block_docs.py"Repository: Significant-Gravitas/AutoGPT
Length of output: 54
🏁 Script executed:
# Search for table row generation logic
rg -A 10 -B 5 "visibility|table|row" "./autogpt_platform/backend/scripts/generate_block_docs.py"Repository: Significant-Gravitas/AutoGPT
Length of output: 3587
🏁 Script executed:
# Read more of the generate_block_docs.py to see the full type_to_readable function
sed -n '127,188p' "./autogpt_platform/backend/scripts/generate_block_docs.py"Repository: Significant-Gravitas/AutoGPT
Length of output: 2006
🏁 Script executed:
# Check if enum values are being escaped when inserted into table
sed -n '270,290p' "./autogpt_platform/backend/scripts/generate_block_docs.py"Repository: Significant-Gravitas/AutoGPT
Length of output: 712
🏁 Script executed:
# Search for where type_str is used in table generation
rg -B 5 -A 5 "type_str" "./autogpt_platform/backend/scripts/generate_block_docs.py" | head -40Repository: Significant-Gravitas/AutoGPT
Length of output: 1438
🏁 Script executed:
# Check if there are any references to "friends" in the visibility context
rg -i "friends.*visibility|visibility.*friends" "./autogpt_platform/backend/backend/blocks/ayrshare/"Repository: Significant-Gravitas/AutoGPT
Length of output: 231
🏁 Script executed:
# Look at the full visibility field definition in the Python source
sed -n '90,94p' "./autogpt_platform/backend/backend/blocks/ayrshare/post_to_tiktok.py"Repository: Significant-Gravitas/AutoGPT
Length of output: 296
🏁 Script executed:
# Check if there are other ayrshare block files that might have visibility field with "friends"
find "./autogpt_platform/backend/backend/blocks/ayrshare/" -name "*.py" -type fRepository: Significant-Gravitas/AutoGPT
Length of output: 1100
Critical: Malformed table row with unescaped pipes in type field (MD056).
Line 37 shows 6 cells instead of 4 because the visibility type contains unescaped pipe characters. The generate_block_docs.py script at lines 280–284 escapes pipes in the description column but not in the type column, causing the enum values ("public" | "private" | "followers") to be treated as separate table cells.
Additionally, the field description mentions 'friends' as a visibility option, but the TikTokVisibility enum (lines 16–20 in post_to_tiktok.py) only defines three values: PUBLIC, PRIVATE, and FOLLOWERS—no FRIENDS option exists.
Fixes required:
- In
generate_block_docs.py(lines 280–284), escape pipe characters intype_strbefore inserting into the table row - Either add
FRIENDSto theTikTokVisibilityenum or update the field description to remove the mention of'friends'
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
37-37: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/ayrshare/post_to_tiktok.md at line 37, The
table row is malformed because pipe characters in the type column aren’t escaped
and the docs mention a non-existent 'FRIENDS' visibility; update the docs
generator to escape pipes in the type string (ensure the code that builds the
table row escapes "|" in the variable type_str, e.g., replace "|" with "\|",
before concatenating the row) and reconcile the TikTok visibility options by
either adding FRIENDS to the TikTokVisibility enum in post_to_tiktok.py or
removing 'friends' from the visibility description so the enum and docs match.
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | linkedin_url | LinkedIn profile URL to fetch data from | str | Yes | | ||
| | fallback_to_cache | Cache usage if live fetch fails | "on-error" | "never" | No | | ||
| | use_cache | Cache utilization strategy | "if-present" | "never" | No | | ||
| | include_skills | Include skills data | bool | No | | ||
| | include_inferred_salary | Include inferred salary data | bool | No | | ||
| | include_personal_email | Include personal email | bool | No | | ||
| | include_personal_contact_number | Include personal contact number | bool | No | | ||
| | include_social_media | Include social media profiles | bool | No | | ||
| | include_extra | Include additional data | bool | No | | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n docs/content/platform/blocks/enrichlayer/linkedin.md | head -30Repository: Significant-Gravitas/AutoGPT
Length of output: 1385
Fix malformed input table structure.
Lines 18–19 contain malformed table rows where the Type column lists union types ("on-error" | "never" and "if-present" | "never") with unescaped pipes, creating 5 cells instead of 4. The table header has 4 columns, causing these rows to misrender.
🔎 Proposed fix for table column alignment
| Input | Description | Type | Required |
|-------|-------------|------|----------|
| linkedin_url | LinkedIn profile URL to fetch data from | str | Yes |
- | fallback_to_cache | Cache usage if live fetch fails | "on-error" | "never" | No |
+ | fallback_to_cache | Cache usage if live fetch fails | "on-error" \| "never" | No |
- | use_cache | Cache utilization strategy | "if-present" | "never" | No |
+ | use_cache | Cache utilization strategy | "if-present" \| "never" | No |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | linkedin_url | LinkedIn profile URL to fetch data from | str | Yes | | |
| | fallback_to_cache | Cache usage if live fetch fails | "on-error" | "never" | No | | |
| | use_cache | Cache utilization strategy | "if-present" | "never" | No | | |
| | include_skills | Include skills data | bool | No | | |
| | include_inferred_salary | Include inferred salary data | bool | No | | |
| | include_personal_email | Include personal email | bool | No | | |
| | include_personal_contact_number | Include personal contact number | bool | No | | |
| | include_social_media | Include social media profiles | bool | No | | |
| | include_extra | Include additional data | bool | No | | |
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | linkedin_url | LinkedIn profile URL to fetch data from | str | Yes | | |
| | fallback_to_cache | Cache usage if live fetch fails | "on-error" \| "never" | No | | |
| | use_cache | Cache utilization strategy | "if-present" \| "never" | No | | |
| | include_skills | Include skills data | bool | No | | |
| | include_inferred_salary | Include inferred salary data | bool | No | | |
| | include_personal_email | Include personal email | bool | No | | |
| | include_personal_contact_number | Include personal contact number | bool | No | | |
| | include_social_media | Include social media profiles | bool | No | | |
| | include_extra | Include additional data | bool | No | |
🧰 Tools
🪛 LanguageTool
[uncategorized] ~17-~17: The name of this social business platform is spelled with a capital “I”.
Context: ...----|-------------|------|----------| | linkedin_url | LinkedIn profile URL to fetch dat...
(LINKEDIN)
🪛 markdownlint-cli2 (0.18.1)
15-15: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
18-18: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
19-19: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/enrichlayer/linkedin.md around lines 15 - 26,
The table rows for fallback_to_cache and use_cache are malformed because their
Type cells contain unescaped pipe characters; to fix, update the two rows
(fallback_to_cache and use_cache) so the union types are rendered as single cell
values by escaping the pipe characters or wrapping the entire Type value in
inline code/backticks (e.g., `on-error | never` and `if-present | never`),
ensuring each row has exactly four columns and the table header aligns
correctly.
| # Exa Search | ||
|
|
||
| ### What it is | ||
| Searches the web using Exa's advanced search API. | ||
|
|
||
| ### What it does | ||
| Searches the web using Exa's advanced search API | ||
|
|
||
| ### How it works | ||
| <!-- MANUAL: how_it_works --> | ||
| _Add technical explanation here._ | ||
| <!-- END MANUAL --> |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
find . -type f -name "search.md" | grep -i exaRepository: Significant-Gravitas/AutoGPT
Length of output: 116
🏁 Script executed:
cat -n docs/content/platform/blocks/exa/search.mdRepository: Significant-Gravitas/AutoGPT
Length of output: 2633
Fix critical markdown validation failures: heading structure and malformed table columns.
The file contains multiple rendering-blocking issues:
-
Heading level violation (MD001) at line 3: Jumps from h1 to h3, skipping h2. Change line 3 to
## What it isor remove the h1 at line 1. -
Broken table column parsing (MD056) at lines 18–19: The table header has 4 columns, but these rows have 5–6 pipe-separated values. The pipe characters in type values (e.g.,
"keyword" | "neural" | "fast") are incorrectly parsed as column delimiters. Replace with comma-separated or backtick-formatted values:keyword, neural, fastor`keyword`, `neural`, `fast`. -
Missing blank line before table (MD058) at line 14: Add a blank line between the
### Inputsheading and the table start. -
Capitalization: Line 19 contains "github" and "linkedin"—should be "GitHub" and "LinkedIn" per naming conventions.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/exa/search.md around lines 1 - 12, The document
has markdown validation errors: the top-level heading jumps from H1 to H3
(MD001), the Inputs table lacks a preceding blank line (MD058) and its rows
incorrectly use pipe characters inside type cells causing mismatched columns
(MD056), plus capitalization issues for GitHub/LinkedIn. Fix by changing the H3
"What it is" to an H2 (or remove the H1) to restore proper heading hierarchy,
insert a blank line before the "### Inputs" section, and update the table so
type values do not include unescaped pipes—use comma-separated or
backtick-wrapped values (e.g., keyword, neural, fast or `keyword`, `neural`,
`fast`) so the header and rows have the same number of columns; also normalize
"github" and "linkedin" to "GitHub" and "LinkedIn".
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | monitor_id | The ID of the monitor to update | str | Yes | | ||
| | status | New status for the monitor | "enabled" | "disabled" | "paused" | No | | ||
| | cron_expression | New cron expression for scheduling | str | No | | ||
| | timezone | New timezone for the schedule | str | No | | ||
| | metadata | New metadata for the monitor | Dict[str, True] | No | | ||
|
|
||
| ### Outputs | ||
| | Output | Description | Type | | ||
| |--------|-------------|------| | ||
| | error | Error message if the operation failed | str | | ||
| | monitor_id | The unique identifier for the monitor | str | | ||
| | status | Updated status of the monitor | str | | ||
| | next_run_at | When the monitor will next run | str | | ||
| | updated_at | When the monitor was updated | str | | ||
| | success | Whether the update was successful | str | |
There was a problem hiding this comment.
Fix malformed type column in Update Monitor Inputs table (line 177).
Line 177 has type annotation "enabled" | "disabled" | "paused" which breaks table parsing (creating 6 cells instead of 4 per MD056). Reformat as:
-| status | New status for the monitor | "enabled" | "disabled" | "paused" | No |
+| status | New status for the monitor | string (enabled/disabled/paused) | No |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | monitor_id | The ID of the monitor to update | str | Yes | | |
| | status | New status for the monitor | "enabled" | "disabled" | "paused" | No | | |
| | cron_expression | New cron expression for scheduling | str | No | | |
| | timezone | New timezone for the schedule | str | No | | |
| | metadata | New metadata for the monitor | Dict[str, True] | No | | |
| ### Outputs | |
| | Output | Description | Type | | |
| |--------|-------------|------| | |
| | error | Error message if the operation failed | str | | |
| | monitor_id | The unique identifier for the monitor | str | | |
| | status | Updated status of the monitor | str | | |
| | next_run_at | When the monitor will next run | str | | |
| | updated_at | When the monitor was updated | str | | |
| | success | Whether the update was successful | str | | |
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | monitor_id | The ID of the monitor to update | str | Yes | | |
| | status | New status for the monitor | string (enabled/disabled/paused) | No | | |
| | cron_expression | New cron expression for scheduling | str | No | | |
| | timezone | New timezone for the schedule | str | No | | |
| | metadata | New metadata for the monitor | Dict[str, True] | No | | |
| ### Outputs | |
| | Output | Description | Type | | |
| |--------|-------------|------| | |
| | error | Error message if the operation failed | str | | |
| | monitor_id | The unique identifier for the monitor | str | | |
| | status | Updated status of the monitor | str | | |
| | next_run_at | When the monitor will next run | str | | |
| | updated_at | When the monitor was updated | str | | |
| | success | Whether the update was successful | str | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
174-174: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
177-177: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
183-183: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/exa/websets_monitor.md around lines 174 - 190,
The Inputs table’s Type cell for the status row is malformed because it contains
pipe characters ("enabled" | "disabled" | "paused") which break the Markdown
table; fix the Update Monitor Inputs table by changing the status Type cell to a
simple type (e.g., str) and move the allowed values into the Description (e.g.,
"New status for the monitor — allowed values: enabled, disabled, paused") or add
a separate Allowed Values column, ensuring no raw pipe characters remain in any
Type cell so the table parses correctly.
| ### What it is | ||
| Cancel all operations being performed on a Webset. | ||
|
|
||
| ### What it does | ||
| Cancel all operations being performed on a Webset | ||
|
|
||
| ### How it works | ||
| <!-- MANUAL: how_it_works --> | ||
| _Add technical explanation here._ | ||
| <!-- END MANUAL --> |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's look at the actual file to confirm the heading structure
cat -n docs/content/platform/blocks/exa/websets.md | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 683
🏁 Script executed:
# Search for the generate_block_docs.py script
find . -name "generate_block_docs.py" -o -name "*generate*block*" -type f | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 192
🏁 Script executed:
# Check for any documentation generation scripts
find . -path "*/node_modules" -prune -o -name "*.py" -type f -exec grep -l "block.*doc\|doc.*block" {} \; | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 441
🏁 Script executed:
# Check the generate_block_docs.py script size and content
wc -l ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 133
🏁 Script executed:
# Look for markdown linting configuration
find . -name ".markdownlint*" -o -name "markdownlint.json" -o -name ".mdlint*" | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 54
🏁 Script executed:
# Check for markdown style guide documentation
find . -path "*/node_modules" -prune -o -name "*.md" -type f -exec grep -l "heading\|markdown.*style\|MD001\|MD002" {} \; | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 172
🏁 Script executed:
# Read the generate_block_docs.py script to find heading level generation
cat -n ./autogpt_platform/backend/scripts/generate_block_docs.py | grep -A 5 -B 5 "What it is\|What it does\|###\|##" | head -60Repository: Significant-Gravitas/AutoGPT
Length of output: 2570
🏁 Script executed:
# Check the blocks.md file for its heading structure
cat -n ./docs/content/platform/blocks/blocks.md | head -50Repository: Significant-Gravitas/AutoGPT
Length of output: 4844
🏁 Script executed:
# Check another generated file to confirm heading pattern
head -30 ./docs/content/platform/blocks/notion/read_page_markdown.md | cat -nRepository: Significant-Gravitas/AutoGPT
Length of output: 1417
🏁 Script executed:
# Check the full structure of websets.md to see how multiple blocks are organized
grep "^#" docs/content/platform/blocks/exa/websets.md | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 401
🏁 Script executed:
# Check if the markdown follows MD002 rule (heading increment)
grep -n "^##\|^###\|^#" docs/content/platform/blocks/exa/websets.md | head -30Repository: Significant-Gravitas/AutoGPT
Length of output: 668
🏁 Script executed:
# Verify the pattern continues through the entire file
grep -n "^#" docs/content/platform/blocks/exa/websets.md | tail -30Repository: Significant-Gravitas/AutoGPT
Length of output: 691
🏁 Script executed:
# Check how many blocks total and their structure
grep -c "^## Exa\|^# Exa" docs/content/platform/blocks/exa/websets.mdRepository: Significant-Gravitas/AutoGPT
Length of output: 74
🏁 Script executed:
# Look at the exact code in generate_block_docs.py for subsection generation
sed -n '352,420p' ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 2554
🏁 Script executed:
# Check if there's a way subsection heading level is supposed to be calculated
grep -n "subsection\|subheading" ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 54
🏁 Script executed:
# Look at the complete generate_block_markdown function signature and see if there's any parameter for heading adjustment
sed -n '340,360p' ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 647
🏁 Script executed:
# Check if other documentation files in the platform show the same first-block H1→H3 pattern
for file in docs/content/platform/blocks/*/[a-z_]*.md; do
first_heading=$(grep -m1 "^# " "$file" 2>/dev/null)
if [ -n "$first_heading" ]; then
second_heading=$(grep "^### " "$file" 2>/dev/null | head -1)
if [ -n "$second_heading" ]; then
echo "File: $file - H1 followed by H3"
fi
fi
done | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 837
Fix heading hierarchy: subsection headings must adjust based on block heading level to avoid skipping heading levels.
The first block in each generated documentation file uses H1 for the block title but H3 for subsections ("What it is", "What it does", etc.), which violates proper markdown heading hierarchy by skipping H2. Subsequent blocks correctly use H2 for titles and H3 for subsections.
This pattern is systematic across all generated block documentation files (airtable, apollo, ayrshare, and others). The issue originates in generate_block_docs.py where subsection headings are hardcoded as ### (H3) regardless of the block's heading level. The script should generate H2 subsections when the block uses H1, and H3 subsections when the block uses H2.
Correct structure should be:
# Block Name (first block)
## What it is
## What it does
...
## Next Block (subsequent blocks)
### What it is
### What it does
Update generate_block_docs.py to calculate subsection heading levels dynamically before merge.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
| ### Inputs | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | expansions | Choose what extra information you want to get with your Twitter Lists: | ||
| - Select 'List_Owner_ID' to get details about who owns the list | ||
|
|
||
| This will let you see more details about the list owner when you also select user fields below. | ListExpansionsFilter | No | | ||
| | user_fields | Choose what information you want to see about list owners. This only works when you select 'List_Owner_ID' in expansions above. | ||
|
|
||
| You can see things like: | ||
| - Their username | ||
| - Profile picture | ||
| - Account details | ||
| - And more | TweetUserFieldsFilter | No | | ||
| | list_fields | Choose what information you want to see about the Twitter Lists themselves, such as: | ||
| - List name | ||
| - Description | ||
| - Number of followers | ||
| - Number of members | ||
| - Whether it's private | ||
| - Creation date | ||
| - And more | ListFieldsFilter | No | | ||
| | list_id | The ID of the List to lookup | str | Yes | |
There was a problem hiding this comment.
Fix markdown table formatting for multi-line cell content (expansions and user_fields inputs).
Lines 17–20 and 73–76 embed bullet lists within table cells, causing MD055/MD056 violations.
Example (lines 17–20):
| expansions | Choose what extra information you want to get with your Twitter Lists:
- Select 'List_Owner_ID' to get details about who owns the list
...
This will let you see more details about the list owner... | ListExpansionsFilter | No |
Reformat as single-line text or move complex descriptions outside tables.
This pattern repeats throughout the file. Generation script must be fixed before merge.
🧰 Tools
🪛 LanguageTool
[style] ~21-~21: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...er_fields | Choose what information you want to see about list owners. This only works ...
(REP_WANT_TO_VB)
[style] ~28-~28: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...st_fields | Choose what information you want to see about the Twitter Lists themselves,...
(REP_WANT_TO_VB)
[grammar] ~36-~36: Ensure spelling is correct
Context: ... No | | list_id | The ID of the List to lookup | str | Yes | ### Outputs | Output | D...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
15-15: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
17-17: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
17-17: Table column count
Expected: 4; Actual: 2; Too few cells, row will be missing data
(MD056, table-column-count)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
| ### Inputs | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | expansions | Choose what extra information you want to get with your Twitter Lists: | ||
| - Select 'List_Owner_ID' to get details about who owns the list | ||
|
|
||
| This will let you see more details about the list owner when you also select user fields below. | ListExpansionsFilter | No | | ||
| | user_fields | Choose what information you want to see about list owners. This only works when you select 'List_Owner_ID' in expansions above. | ||
|
|
||
| You can see things like: | ||
| - Their username | ||
| - Profile picture | ||
| - Account details | ||
| - And more | TweetUserFieldsFilter | No | | ||
| | list_fields | Choose what information you want to see about the Twitter Lists themselves, such as: | ||
| - List name | ||
| - Description | ||
| - Number of followers | ||
| - Number of members | ||
| - Whether it's private | ||
| - Creation date | ||
| - And more | ListFieldsFilter | No | | ||
|
|
There was a problem hiding this comment.
Critical: Fix multi-line table cells that break markdown syntax.
Markdown tables do not support line breaks within cells. Lines 17-20, 21-27, and 28-35 contain multi-line descriptions with embedded newlines and list formatting, which will not parse as valid table cells. These must be flattened to single lines.
🔎 Example fix for multi-line cells
| Input | Description | Type | Required |
|-------|-------------|------|----------|
- | expansions | Choose what extra information you want to get with your Twitter Lists:
- - Select 'List_Owner_ID' to get details about who owns the list
-
- This will let you see more details about the list owner when you also select user fields below. | ListExpansionsFilter | No |
+ | expansions | Choose what extra information you want to get with your Twitter Lists. Select 'List_Owner_ID' to get details about who owns the list. This provides more details about the list owner when you also select user fields. | ListExpansionsFilter | No |
- | user_fields | Choose what information you want to see about list owners. This only works when you select 'List_Owner_ID' in expansions above.
-
- You can see things like:
- - Their username
- - Profile picture
- - Account details
- - And more | TweetUserFieldsFilter | No |
+ | user_fields | Choose information about list owners (username, profile picture, account details, etc.). Only works when 'List_Owner_ID' is selected in expansions. | TweetUserFieldsFilter | No |
- | list_fields | Choose what information you want to see about the Twitter Lists themselves, such as:
- - List name
- - Description
- - Number of followers
- - Number of members
- - Whether it's private
- - Creation date
- - And more | ListFieldsFilter | No |
+ | list_fields | Choose information about Twitter Lists (name, description, followers, members, privacy status, creation date, etc.). | ListFieldsFilter | No |This is a critical generation bug that breaks table rendering. The generator should produce single-line descriptions in tables.
🧰 Tools
🪛 LanguageTool
[style] ~21-~21: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...er_fields | Choose what information you want to see about list owners. This only works ...
(REP_WANT_TO_VB)
[style] ~28-~28: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...st_fields | Choose what information you want to see about the Twitter Lists themselves,...
(REP_WANT_TO_VB)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/twitter/pinned_lists.md around lines 14 - 36,
The table cells for the Inputs column contain multi-line descriptions that break
Markdown table parsing; flatten the descriptions for the expansions,
user_fields, and list_fields rows into single-line text (remove embedded
newlines and list bullets, replacing them with commas or semicolon-separated
phrases) so each cell is one continuous line; ensure the header row and pipe
separators remain unchanged and that the cell content for the symbols
"expansions", "user_fields", and "list_fields" becomes a single-line description
each.
🧩 Analysis chain
🏁 Script executed:
# First, check if the file exists and read its content around lines 14-36
find . -name "pinned_lists.md" -type fRepository: Significant-Gravitas/AutoGPT
Length of output: 126
🏁 Script executed:
# Read the specific lines from the file
sed -n '14,36p' ./docs/content/platform/blocks/twitter/pinned_lists.mdRepository: Significant-Gravitas/AutoGPT
Length of output: 954
🏁 Script executed:
# Search for generate_block_docs.py
find . -name "generate_block_docs.py" -type fRepository: Significant-Gravitas/AutoGPT
Length of output: 129
🏁 Script executed:
# Read the generator script to understand how it creates table cells
cat -n ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 29583
🏁 Script executed:
# Find the Twitter pinned_lists block implementation
find . -path "*/blocks/*" -name "*pinned*" -type f | grep -i twitterRepository: Significant-Gravitas/AutoGPT
Length of output: 198
🏁 Script executed:
# Read the block implementation to see field descriptions
cat -n ./autogpt_platform/backend/backend/blocks/twitter/lists/pinned_lists.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 11231
🏁 Script executed:
# Find ListExpansionInputs to see the field descriptions
find . -path "*/blocks/twitter*" -name "*.py" -exec grep -l "class ListExpansionInputs" {} \;Repository: Significant-Gravitas/AutoGPT
Length of output: 131
🏁 Script executed:
# Read the _types.py file to find ListExpansionInputs and field descriptions
cat -n ./autogpt_platform/backend/backend/blocks/twitter/_types.py | head -200Repository: Significant-Gravitas/AutoGPT
Length of output: 6832
🏁 Script executed:
# Continue reading the _types.py file to find ListExpansionInputs
cat -n ./autogpt_platform/backend/backend/blocks/twitter/_types.py | tail -200Repository: Significant-Gravitas/AutoGPT
Length of output: 10652
🏁 Script executed:
# Check if there are other blocks with similar multi-line descriptions to see if this is widespread
grep -r "\\\\n" ./autogpt_platform/backend/backend/blocks/ --include="*.py" | grep "SchemaField" | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 54
🏁 Script executed:
# Search for multi-line descriptions (with actual newlines) in SchemaField definitions
grep -A 2 "SchemaField(" ./autogpt_platform/backend/backend/blocks/twitter/_types.py | grep -B 2 "description=" | grep -E "\\\\n|description=" | head -40Repository: Significant-Gravitas/AutoGPT
Length of output: 4365
🏁 Script executed:
# Let's verify the exact source descriptions for the three problematic fields
sed -n '387,406p' ./autogpt_platform/backend/backend/blocks/twitter/_types.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 1460
🌐 Web query:
markdown table cells multi-line support CommonMark GFM rendering
💡 Result:
Short answer: CommonMark/GFM pipe tables do not support multiline (block-level) content inside a single table cell. Cells are treated as single-line inline content; block elements or real multi-paragraph/multi-row cells are not allowed. Use HTML
(or ainside a cell) when you need true multiline/block content. [1][2][3][4]
Sources
- GitHub Flavored Markdown spec (tables section). [1]
- CommonMark / GFM discussion and docs (tables cannot contain block elements). [2]
- Pandoc docs on pipe tables (cells cannot contain block elements or span multiple lines). [3]
- Implementations/issues (markdown-it / others note lack of multi-line cell support). [4]
🏁 Script executed:
# Check if there's a docs build system or if these files are processed specially
find ./docs -name "*.py" -o -name "mkdocs.yml" -o -name "*.toml" | grep -E "(mkdocs|build|process)" | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 89
🏁 Script executed:
# Check the mkdocs configuration to understand how tables are rendered
cat ./docs/mkdocs.yml | head -100Repository: Significant-Gravitas/AutoGPT
Length of output: 4295
🏁 Script executed:
# Let's verify how the descriptions are actually rendered by checking if the table breaks
# by looking at nearby context to see if there are any rendering issues in the raw file
cat -n ./docs/content/platform/blocks/twitter/pinned_lists.md | head -50Repository: Significant-Gravitas/AutoGPT
Length of output: 2155
Fix invalid markdown table syntax caused by newlines in field descriptions.
The generator script creates broken markdown tables by inserting literal newlines from descriptions directly into pipe table cells. Lines 17-20, 21-27, and 28-35 contain multi-line content that violates GFM pipe table syntax. Markdown tables require single-line cells; block elements and newlines are not supported per the CommonMark/GFM specification.
Root cause: generate_block_docs.py lines 394-395 only escape pipes but do not handle newlines in descriptions. Source descriptions in _types.py contain \n escape sequences that become literal newlines in the output.
Fix the generator to either collapse newlines and bullet points into single-line descriptions, or escape/strip them before inserting into table cells.
🧰 Tools
🪛 LanguageTool
[style] ~21-~21: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...er_fields | Choose what information you want to see about list owners. This only works ...
(REP_WANT_TO_VB)
[style] ~28-~28: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...st_fields | Choose what information you want to see about the Twitter Lists themselves,...
(REP_WANT_TO_VB)
🧩 Analysis chain
🏁 Script executed:
# First, check if the file exists and read lines 14-36
if [ -f "docs/content/platform/blocks/twitter/pinned_lists.md" ]; then
echo "File exists. Reading lines 14-36:"
sed -n '14,36p' "docs/content/platform/blocks/twitter/pinned_lists.md"
else
echo "File not found. Searching for similar files..."
find . -name "*pinned_lists*" -type f 2>/dev/null
fiRepository: Significant-Gravitas/AutoGPT
Length of output: 988
🏁 Script executed:
# Also check the total line count of the file
if [ -f "docs/content/platform/blocks/twitter/pinned_lists.md" ]; then
wc -l "docs/content/platform/blocks/twitter/pinned_lists.md"
fiRepository: Significant-Gravitas/AutoGPT
Length of output: 128
🏁 Script executed:
# Check for markdown configuration, parser setup, or docs generation
find . -name "*.json" -o -name "*.yaml" -o -name "*.yml" -o -name "*.config.*" | grep -E "(doc|markdown|config)" | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 1029
🏁 Script executed:
# Search for documentation about markdown syntax or any markdown linting config
find . -type f \( -name ".markdownlint*" -o -name "markdownlint*" -o -name "*markdown*config*" \) 2>/dev/nullRepository: Significant-Gravitas/AutoGPT
Length of output: 54
🏁 Script executed:
# Check if there's a docs build process or any scripts related to documentation
ls -la docs/ 2>/dev/null | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 620
🏁 Script executed:
# Look for any validation or linting rules related to tables in markdown
rg -i "table|markdown" --type yaml --type json docs/ 2>/dev/null | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 372
🏁 Script executed:
# Read the mkdocs.yml to see full table configuration
cat -n docs/mkdocs.yml | head -50Repository: Significant-Gravitas/AutoGPT
Length of output: 2574
🏁 Script executed:
# Search for table-reader extension documentation or usage in the codebase
rg "table-reader" -A 5 -B 5 --type yaml --type mdRepository: Significant-Gravitas/AutoGPT
Length of output: 429
🏁 Script executed:
# Check if there are any GitHub workflows or CI that validate markdown syntax
cat -n .github/workflows/docs-enhance.yml | head -100Repository: Significant-Gravitas/AutoGPT
Length of output: 4416
🏁 Script executed:
# Check the requirements.txt to see what markdown processing is being used
cat docs/requirements.txtRepository: Significant-Gravitas/AutoGPT
Length of output: 422
🏁 Script executed:
# Search for any markdown validation or linting in pre-commit config
cat -n .pre-commit-config.yamlRepository: Significant-Gravitas/AutoGPT
Length of output: 12552
🏁 Script executed:
# Look for any GitHub Actions that build or validate the documentation
cat .github/workflows/docs-block-sync.yml | head -80Repository: Significant-Gravitas/AutoGPT
Length of output: 2614
🏁 Script executed:
# Check if there are any recent commits or issues related to markdown table formatting
rg -i "markdown.*table|table.*markdown" docs/ -l --type md | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 154
🏁 Script executed:
# Search for the generate_block_docs.py script to understand how it generates tables
find . -name "generate_block_docs.py" -type f 2>/dev/nullRepository: Significant-Gravitas/AutoGPT
Length of output: 129
🏁 Script executed:
# Check if table-reader plugin supports multi-line cells - search for its documentation or config
rg "table.reader|table-reader" -i . --type py --type yaml -A 10 -B 2 2>/dev/null | head -100Repository: Significant-Gravitas/AutoGPT
Length of output: 601
🌐 Web query:
mkdocs-table-reader-plugin multi-line cells support markdown tables
💡 Result:
Short answer: Not directly — mkdocs-table-reader-plugin converts tables via pandas.DataFrame.to_markdown(), so multiline cell behavior depends on pandas/tabulate and the Markdown renderer (Markdown/GFM used by MkDocs). Standard GFM tables don't support true multi-line cells; you can work around it by encoding line breaks as HTML (
) in the source, using the plugin's read_raw() to supply prebuilt markdown/HTML, or using a renderer that supports Pandoc-style multiline tables. See below for sources.
References
- mkdocs-table-reader-plugin readers & behavior (uses pandas.to_markdown()). [1]
- pandas.DataFrame.to_markdown() (uses tabulate; output is plain Markdown string). [2]
- Markdown/GFM multiline-cell limitations and workarounds (use
or Pandoc multiline tables). [3]
🏁 Script executed:
# Read the generate_block_docs.py script to see how it generates tables with multi-line cells
cat -n ./autogpt_platform/backend/scripts/generate_block_docs.py | head -200Repository: Significant-Gravitas/AutoGPT
Length of output: 6987
🏁 Script executed:
# Search for how the script formats table descriptions
rg "Description|expansions|user_fields|list_fields" ./autogpt_platform/backend/scripts/generate_block_docs.py -A 3 -B 3Repository: Significant-Gravitas/AutoGPT
Length of output: 989
🏁 Script executed:
# Search for where the description is being set in the table rows
rg "inp\.|description" ./autogpt_platform/backend/scripts/generate_block_docs.py -A 5 -B 5 | head -150Repository: Significant-Gravitas/AutoGPT
Length of output: 5008
🏁 Script executed:
# Get more context around the table generation
sed -n '370,450p' ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 3108
🏁 Script executed:
# Check the actual block definition to see where these multi-line descriptions come from
find ./autogpt_platform/backend/backend/blocks -name "*twitter*" -o -name "*pinned*" 2>/dev/null | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 193
🏁 Script executed:
# Look for the Twitter block implementation
find ./autogpt_platform/backend/backend/blocks -type f -name "*.py" | xargs rg -l "pinned_lists|PinnedLists" 2>/dev/nullRepository: Significant-Gravitas/AutoGPT
Length of output: 204
🏁 Script executed:
# Read the pinned_lists.py block definition to see where descriptions come from
cat -n ./autogpt_platform/backend/backend/blocks/twitter/lists/pinned_lists.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 11231
🏁 Script executed:
# Find the ListExpansionInputs definition
rg "class ListExpansionInputs" ./autogpt_platform/backend/backend/blocks/twitter -A 50Repository: Significant-Gravitas/AutoGPT
Length of output: 5651
🏁 Script executed:
# Create a test markdown file with the exact content to verify if it renders
mkdir -p /tmp/test_markdown
cat > /tmp/test_markdown/test.md << 'EOF'
### Inputs
| Input | Description | Type | Required |
|-------|-------------|------|----------|
| expansions | Choose what extra information you want to get with your Twitter Lists:
- Select 'List_Owner_ID' to get details about who owns the list
This will let you see more details about the list owner when you also select user fields below. | ListExpansionsFilter | No |
| user_fields | Choose what information you want to see about list owners. This only works when you select 'List_Owner_ID' in expansions above.
You can see things like:
- Their username
- Profile picture
- Account details
- And more | TweetUserFieldsFilter | No |
EOF
cat /tmp/test_markdown/test.mdRepository: Significant-Gravitas/AutoGPT
Length of output: 708
🏁 Script executed:
# Now test if this markdown can be parsed correctly by a standard markdown parser
python3 << 'EOF'
import markdown
from pathlib import Path
# Read the test markdown
content = Path('/tmp/test_markdown/test.md').read_text()
# Parse with markdown
html = markdown.markdown(content, extensions=['tables'])
print("=== HTML Output ===")
print(html)
print("\n=== Analysis ===")
if '<table>' not in html:
print("ERROR: No table generated - markdown table syntax is broken!")
else:
print("Table was generated, but check structure:")
# Count table rows
row_count = html.count('<tr>')
print(f"Number of table rows: {row_count}")
if row_count < 4:
print("WARNING: Expected at least 4 rows (header + 3 data rows) but got fewer")
EOFRepository: Significant-Gravitas/AutoGPT
Length of output: 192
🏁 Script executed:
# Install markdown and test parsing
pip install markdown -q && python3 << 'EOF'
import markdown
from pathlib import Path
# Read the test markdown
content = Path('/tmp/test_markdown/test.md').read_text()
# Parse with markdown
html = markdown.markdown(content, extensions=['tables'])
print("=== HTML Output ===")
print(html)
print("\n=== Analysis ===")
if '<table>' not in html:
print("ERROR: No table generated - markdown table syntax is broken!")
else:
print("✓ Table was generated")
# Count table rows
row_count = html.count('<tr>')
print(f"Number of table rows: {row_count}")
if row_count < 4:
print("WARNING: Expected at least 4 rows (header + 3 data rows) but got fewer")
# Check for incomplete parsing
if 'Choose what extra information' in html and 'ListExpansionsFilter' not in html:
print("⚠️ PROBLEM: Cell content was not properly closed - description extends past the cell")
EOFRepository: Significant-Gravitas/AutoGPT
Length of output: 1254
🏁 Script executed:
# Verify the script is not stripping newlines from descriptions
grep -A 10 "desc = inp.description" ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 526
🏁 Script executed:
# Test if escaping newlines would fix the issue
python3 << 'EOF'
import markdown
# Create a version with escaped newlines
content_escaped = """### Inputs
| Input | Description | Type | Required |
|-------|-------------|------|----------|
| expansions | Choose what extra information you want to get with your Twitter Lists: Select 'List_Owner_ID' to get details about who owns the list. This will let you see more details about the list owner when you also select user fields below. | ListExpansionsFilter | No |
| user_fields | Choose what information you want to see about list owners. This only works when you select 'List_Owner_ID' in expansions above. You can see: username, profile picture, account details, and more. | TweetUserFieldsFilter | No |
"""
html = markdown.markdown(content_escaped, extensions=['tables'])
print("=== Fixed Version (single-line descriptions) ===")
print("HTML table rows:", html.count('<tr>'))
if '<td>ListExpansionsFilter</td>' in html and '<td>TweetUserFieldsFilter</td>' in html:
print("✓ FIXED: All cells are properly parsed with correct types and values in all columns")
else:
print("✗ PROBLEM: Still not working")
EOFRepository: Significant-Gravitas/AutoGPT
Length of output: 223
Fix multi-line table cells that break markdown table syntax.
Markdown tables don't support line breaks within cells. The descriptions in the expansions, user_fields, and list_fields cells contain literal newlines that fragment the table structure. When parsed by standard markdown, these cells break the table: the description content spans multiple rows, Type and Required columns become empty, and remaining content spills outside the table as raw text.
The source of these multi-line descriptions is autogpt_platform/backend/backend/blocks/twitter/_types.py in the ListExpansionInputs class, where field definitions include \n characters. The generate_block_docs.py script escapes pipes in descriptions but does not handle newlines, so they're inserted directly into table cells.
Flatten these descriptions to single lines:
Example fix
- | expansions | Choose what extra information you want to get with your Twitter Lists:
- - Select 'List_Owner_ID' to get details about who owns the list
-
- This will let you see more details about the list owner when you also select user fields below. | ListExpansionsFilter | No |
+ | expansions | Choose what extra information you want to get with your Twitter Lists. Select 'List_Owner_ID' to get details about who owns the list and see more details about the list owner when you select user fields below. | ListExpansionsFilter | No |
- | user_fields | Choose what information you want to see about list owners. This only works when you select 'List_Owner_ID' in expansions above.
-
- You can see things like:
- - Their username
- - Profile picture
- - Account details
- - And more | TweetUserFieldsFilter | No |
+ | user_fields | Choose what information you want to see about list owners (username, profile picture, account details, and more). This only works when you select 'List_Owner_ID' in expansions. | TweetUserFieldsFilter | No |
- | list_fields | Choose what information you want to see about the Twitter Lists themselves, such as:
- - List name
- - Description
- - Number of followers
- - Number of members
- - Whether it's private
- - Creation date
- - And more | ListFieldsFilter | No |
+ | list_fields | Choose what information you want to see about Twitter Lists (name, description, followers, members, privacy, creation date, and more). | ListFieldsFilter | No |Update autogpt_platform/backend/backend/blocks/twitter/_types.py to remove \n from the description fields in ListExpansionInputs, and consider updating the generate_block_docs.py script to strip or replace newlines in table cell descriptions to prevent this issue systematically.
🧰 Tools
🪛 LanguageTool
[style] ~21-~21: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...er_fields | Choose what information you want to see about list owners. This only works ...
(REP_WANT_TO_VB)
[style] ~28-~28: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...st_fields | Choose what information you want to see about the Twitter Lists themselves,...
(REP_WANT_TO_VB)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/twitter/pinned_lists.md around lines 14 - 36,
The table in pinned_lists.md is broken by literal newlines in field
descriptions; remove newlines from the source description strings so table cells
are single-line. Edit the ListExpansionInputs field definitions in
autogpt_platform/backend/backend/blocks/twitter/_types.py to strip or replace
'\n' characters (e.g., join lines or replace with spaces) for the descriptions
of expansions, user_fields, and list_fields; additionally update
generate_block_docs.py to sanitize/normalize description text (trim, collapse
newlines to spaces, and escape pipes) before emitting markdown so future
generated tables remain single-line cells.
| ### What it is | ||
| This block retrieves the authenticated user's home timeline. | ||
|
|
||
| ### What it does | ||
| This block retrieves the authenticated user's home timeline. | ||
|
|
||
| ### How it works | ||
| <!-- MANUAL: how_it_works --> | ||
| _Add technical explanation here._ | ||
| <!-- END MANUAL --> |
There was a problem hiding this comment.
Fix heading structure: use H2 for subsections instead of H3.
All subsections ("What it is", "What it does", etc.) use H3 (###) but should use H2 (##).
This is the same heading structure issue flagged in websets.md. Verify that the generation script will be corrected before merge.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/twitter/timeline.md around lines 3 - 12, Change
the subsection headings from H3 to H2 in this document: replace "### What it
is", "### What it does" and "### How it works" with "## What it is", "## What it
does" and "## How it works" respectively, and ensure the same fix is applied
programmatically in the content generation script that produced websets.md so
future files use H2 for these subsections.
| ### Inputs | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | start_time | Start time in YYYY-MM-DDTHH:mm:ssZ format. If set to a time less than 10 seconds ago, it will be automatically adjusted to 10 seconds ago (Twitter API requirement). | str (date-time) | No | | ||
| | end_time | End time in YYYY-MM-DDTHH:mm:ssZ format | str (date-time) | No | | ||
| | since_id | Returns results with Tweet ID greater than this (more recent than), we give priority to since_id over start_time | str | No | | ||
| | until_id | Returns results with Tweet ID less than this (that is, older than), and used with since_id | str | No | | ||
| | sort_order | Order of returned tweets (recency or relevancy) | str | No | | ||
| | expansions | Choose what extra information you want to get with your tweets. For example: | ||
| - Select 'Media_Keys' to get media details | ||
| - Select 'Author_User_ID' to get user information | ||
| - Select 'Place_ID' to get location details | ExpansionFilter | No | | ||
| | media_fields | Select what media information you want to see (images, videos, etc). To use this, you must first select 'Media_Keys' in the expansions above. | TweetMediaFieldsFilter | No | | ||
| | place_fields | Select what location information you want to see (country, coordinates, etc). To use this, you must first select 'Place_ID' in the expansions above. | TweetPlaceFieldsFilter | No | | ||
| | poll_fields | Select what poll information you want to see (options, voting status, etc). To use this, you must first select 'Poll_IDs' in the expansions above. | TweetPollFieldsFilter | No | | ||
| | tweet_fields | Select what tweet information you want to see. For referenced tweets (like retweets), select 'Referenced_Tweet_ID' in the expansions above. | TweetFieldsFilter | No | | ||
| | user_fields | Select what user information you want to see. To use this, you must first select one of these in expansions above: | ||
| - 'Author_User_ID' for tweet authors | ||
| - 'Mentioned_Usernames' for mentioned users | ||
| - 'Reply_To_User_ID' for users being replied to | ||
| - 'Referenced_Tweet_Author_ID' for authors of referenced tweets | TweetUserFieldsFilter | No | | ||
| | max_results | Number of tweets to retrieve (5-100) | int | No | | ||
| | pagination_token | Token for pagination | str | No | |
There was a problem hiding this comment.
Fix markdown table formatting for multi-line cell content (expansions input).
Lines 22–25 embed a bullet list within a table cell, breaking markdown table structure and causing MD055/MD056 violations (missing trailing pipe, column count mismatch).
The input description:
| expansions | Choose what extra information you want to get with your tweets. For example:
- Select 'Media_Keys' to get media details
- Select 'Author_User_ID' to get user information
- Select 'Place_ID' to get location details | ExpansionFilter | No |
Should be reformatted as single-line text or moved to documentation outside the table.
This pattern repeats in lines 79–82 and 137–140. The generation script must properly handle complex descriptions in table cells. Verify before merge.
🧰 Tools
🪛 LanguageTool
[style] ~26-~26: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...lds | Select what media information you want to see (images, videos, etc). To use this,...
(REP_WANT_TO_VB)
[style] ~27-~27: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ... | Select what location information you want to see (country, coordinates, etc). To use...
(REP_WANT_TO_VB)
[style] ~28-~28: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...elds | Select what poll information you want to see (options, voting status, etc). To u...
(REP_WANT_TO_VB)
[style] ~29-~29: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...lds | Select what tweet information you want to see. For referenced tweets (like retwee...
(REP_WANT_TO_VB)
[style] ~30-~30: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...elds | Select what user information you want to see. To use this, you must first select...
(REP_WANT_TO_VB)
🪛 markdownlint-cli2 (0.18.1)
15-15: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
22-22: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
22-22: Table column count
Expected: 4; Actual: 2; Too few cells, row will be missing data
(MD056, table-column-count)
22-22: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/twitter/timeline.md around lines 14 - 36, The
markdown table row for the "expansions" input contains a multi-line bullet list
that breaks the table; change that cell to a single-line description (e.g.,
"Choose extra info to include (e.g., media keys, author user ID, place ID); see
details below.") or move the detailed bullet list out of the table into a short
subsection under the table, and apply the same fix to the other problematic rows
noted (the repeated expansion descriptions around lines 79–82 and 137–140) so
every table row remains a single line and the table column count stays
consistent.
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
| for i, block in enumerate(sorted(file_blocks, key=lambda b: b.name)): | ||
| # Try to extract manual content | ||
| if migrate: | ||
| manual_content = extract_legacy_content(existing_content) |
There was a problem hiding this comment.
Migration mode applies same content to all blocks
Medium Severity
When --migrate is used in write_block_docs, the code calls extract_legacy_content(existing_content) for each block in the loop, where existing_content is the entire file. Since extract_legacy_content uses re.search (which only finds the first match), all blocks in a multi-block file will receive the same manual content from the first block's "How it works" and "Possible use case" sections, rather than each block's own content. The separate migrate_block_docs.py script handles this correctly by finding all block headings and extracting content per-block, but the --migrate flag in this script is publicly documented and will produce incorrect output.
Additional Locations (1)
|
Thank you for working on this documentation auto-generation system. Before this can be merged:
|
|
Thank you for submitting this comprehensive PR to add a block documentation auto-generation system. The implementation looks thorough and well-designed, with scripts for generating docs, preserving manual content, and maintaining synchronization through CI workflows. Before this can be approved, please complete the PR description checklist. You've clearly listed your changes at the top of the description, but the formal checklist items remain unchecked. Please check off the relevant items in the checklist section, particularly:
For the test plan, please include the specific tests you ran to verify this functionality works correctly. Other than that, this is an excellent contribution that will significantly improve documentation maintenance for blocks in the platform. |
|
Your PR adds a valuable documentation generation system for blocks, which will help maintain accurate and consistent docs. The implementation looks solid with Python scripts for generation, preservation of manual content, and appropriate CI workflows. However, I noticed the checklist in your PR description is completely empty. While the PR description itself and the cursor summary do provide good information about what's changing, our process requires the checklist to be filled out. Please complete the checklist items in the PR description, particularly:
Once the checklist is completed, this PR looks ready for review. The documentation automation will be a great improvement for maintaining consistent docs across all blocks. |
…ocumentation Replace placeholder text in MANUAL sections with comprehensive documentation: - Added 2-paragraph technical explanations for how_it_works sections - Added 3 practical use case examples with bold titles for use_case sections Services updated: Twitter, Exa, Ayrshare, Google, GitHub, Firecrawl, Notion, Airtable, Slant3D, Linear, Jina, HubSpot, Apollo, Discord, DataForSEO, Todoist, System, Core blocks (data, logic, misc, multimedia, search, llm), BaaS, Bannerbear, Replicate, Enrichlayer, Wolfram, FAL, Stagehand, SmartLead, Nvidia, Compass, ZeroBounce, and generic webhooks. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
Thank you for this comprehensive PR that adds an automated block documentation generation system. This looks like a valuable addition that will help keep documentation in sync with code. Missing Required InformationBefore this PR can be approved, please complete the PR description template checklist. The current PR has:
Please update the PR description to:
Technical ReviewThe implementation looks solid with:
Once you complete the PR description, this should be ready for review. |
![sentry[bot]](https://avatars.githubusercontent.com/u/1396951?s=60&v=4){kind=small}
| file_path = f"{subdir}/{md_file}" | ||
| else: | ||
| # Use category-based grouping for top-level blocks | ||
| primary_category = block.categories[0] if block.categories else "BASIC" |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
There was a problem hiding this comment.
Actionable comments posted: 19
Note
Due to the large number of review comments, Critical severity comments were prioritized as inline comments.
🤖 Fix all issues with AI agents
In @docs/content/platform/blocks/exa/code_context.md:
- Around line 16-21: The tokens_num row in the Markdown table has five cells
because the type column was split into two cells ("str" and "int"); fix the
tokens_num row in docs/content/platform/blocks/exa/code_context.md by merging
those two cells into a single Type cell with the union type (e.g., "str | int"
or escaped "str \| int" if pipes break the table) so the row has exactly four
columns: Input, Description, Type, Required.
In @docs/content/platform/blocks/exa/contents.md:
- Around line 1-3: The generator generate_block_markdown currently hardcodes
"###" for subsections causing an MD001 heading hierarchy violation; modify
generate_block_markdown to compute a subsection prefix (use "##" when
is_first_in_file is True, otherwise "###") and use that prefix for all
subsection headings ("What it is", "What it does", etc.) instead of the
hardcoded "###", ensuring generated files in docs/content/platform/blocks/ use
h2 subsections for the first file and h3 otherwise.
In @docs/content/platform/blocks/exa/research.md:
- Around line 16-24: The "model" input row in the Inputs table has too many
cells; collapse the enum/type values into the single Type cell for the "model"
row (the row starting with "model") so the table has four columns again,
ensuring values like "exa-research-fast", "exa-research", and "exa-research-pro"
are combined in that Type cell and any pipe characters are escaped or the cell
quoted to avoid splitting; keep the Required column as "No" and preserve the
Description text in its own cell.
In @docs/content/platform/blocks/exa/webhook_blocks.md:
- Line 29: The table row for the metadata/data field currently shows an invalid
type annotation "Dict[str, True]"; update the type to a valid annotation such as
"Dict[str, Any]" (or a more specific generic) in the "metadata/data" entry in
docs/content/platform/blocks/exa/webhook_blocks.md, and if this doc is
auto-generated, fix the generator (scripts/generate_block_docs.py) to emit "Any"
(or the correct type) instead of the boolean literal True when producing
Dict[str, ...] annotations.
In @docs/content/platform/blocks/exa/websets_polling.md:
- Line 81: The generator’s type_to_readable() currently treats a boolean
additionalProperties from Pydantic JSON schema as the literal string "True";
update type_to_readable() in generate_block_docs.py to detect when
schema.get("additionalProperties") is a boolean: if True return "Dict[str, Any]"
(ensure Any is referenced/imported/mentioned in docs context) and if False
return "Dict" (or another concise restricted form) instead of converting the
boolean to a string; apply this change wherever type_to_readable() handles
dict/object schemas so generated docs no longer show Dict[str, True]/Dict[str,
False].
In @docs/content/platform/blocks/exa/websets.md:
- Around line 57-63: Table row for the "metadata" input has too many cells
causing a 4-column mismatch; update the "metadata" row in the Exa Create Or Find
Webset table so it has exactly four pipe-separated cells: "metadata" as the
Input, a concise Description, the Type consolidated to a single cell (e.g.,
"Dict[str, True]" or a clearer type like "Dict[str, Any]") and the Required
column ("No"), ensuring the entire row uses only three pipes to produce four
columns.
In @docs/content/platform/blocks/firecrawl/crawl.md:
- Around line 16-24: The generated markdown table breaks because pipe characters
in type definitions (type_str) are not escaped; update generate_block_docs.py
where table rows are written to replace "|" with "\|" in type_str before writing
(the same escaping used for descriptions), and add an extra newline when
emitting the table heading so there is a blank line before the heading; this
change will fix the formats field (e.g., List["markdown" | "html" | "rawHtml"])
in the generated crawl.md, scrape.md, and search.md files.
In @docs/content/platform/blocks/generic_webhook/triggers.md:
- Around line 1-3: The documentation generator in generate_block_docs.py is
hardcoding "### " for subsection headings which produces an h1 followed
immediately by h3; find the locations that emit subsection headers (search for
the literal "### " in generate_block_docs.py or the function that builds section
headings) and change them to "## " so subsections become h2; keep the
surrounding template/formatting logic intact and rerun the generator to
regenerate the affected block docs.
In @docs/content/platform/blocks/github/checks.md:
- Line 1: Update the heading text and hierarchy: change the main title string "#
Github Create Check Run" to "# GitHub Create Check Run" (fix capitalization) and
replace any "### What it is" headings (including the occurrence at line 48) with
"## What it is" to restore proper h2 hierarchy after the main title; also scan
the file for other "Github" occurrences and correct them to "GitHub".
In @docs/content/platform/blocks/github/statuses.md:
- Line 1: Change the top-level heading text from "Github Create Status" to
"GitHub Create Status" (fix capitalization), promote the two "### What it is"
and "### What it does" headings to h2 ("##") to correct hierarchy, and remove
redundancy by consolidating the nearly identical sections into a single clear
"## What it is / does" section that explains in one place that the block creates
a commit status in a GitHub repository and includes any distinct details
(inputs, outputs, scope) if needed.
In @docs/content/platform/blocks/github/triggers.md:
- Line 1: Rename the top heading "# Github Discussion Trigger" to "# GitHub
Discussion Trigger", change the duplicate "### What it is" and "### What it
does" subsections into a single "## What it does" with concrete behavior (or
keep both but consolidate content), and promote the "###" headings to "##" to
fix hierarchy; apply the same "Github"→"GitHub" and h3→h2 fixes to the other
trigger blocks referenced (the sections starting at lines 51, 101, 146, and 196)
so all headings and duplicate content are corrected consistently.
- Line 49: In the remaining trigger blocks (the Issues, Pull Request, Release,
and Star sections identified by their headings "Issues", "Pull Request",
"Release", and "Star"), apply the same edits as the Discussion block: change
every "Github" title to "GitHub"; convert all subsection headings currently
using h3 (###) to h2 (##); either merge the duplicate "What it is" and "What it
does" into a single descriptive section or clearly differentiate their content;
ensure there is a blank line before and after every Markdown table (especially
the Output tables); in all Output tables replace type annotations "Dict[str,
True]" with "Dict[str, Any]"; and shorten or move long multi-line cell
descriptions out of table cells (put constraints or extended explanations
beneath the table) so table cells remain concise.
In @docs/content/platform/blocks/llm.md:
- Line 446: The docs use the boolean literal "True" as a type in multiple places
(e.g., the conversation_history field and other occurrences), which is invalid;
update those annotations (for example in the conversation_history declaration
`List[Dict[str, True]]` and the other two occurrences) to use a proper type such
as `Any` or the concrete field type (e.g., `Dict[str, Any]` or `List[Dict[str,
Any]]`) so the types are valid and expressive; locate and replace every `True`
used as a type in this file with the appropriate type.
In @docs/content/platform/blocks/misc.md:
- Line 3: The top-level section heading "### What it is" is using h3 but must be
h2; update the heading token from "### What it is" to "## What it is" and, for
other block docs that use the pattern "## Block Name" plus a separate "### What
it is", remove the extra "### What it is" (or merge its content under the
existing "## Block Name") so each block uses a single top-level h2 header like
"## Block Name" and no redundant h3 "What it is".
In @docs/content/platform/blocks/multimedia.md:
- Around line 1-3: Change the top-level heading "Add Audio To Video" from h1 to
h2 so the file uses h2 for block titles and h3 for subsections; specifically
update the headings titled "Add Audio To Video" (first occurrence and the other
two occurrences referenced) from "#" to "##" so they match the later blocks that
use "### What it is"/"### What it does" as subsections and restore a consistent
h2→h3 hierarchy.
- Around line 16-22: All six Markdown tables (the Inputs and Outputs tables
under each block heading) are missing required blank lines; add one blank line
immediately before the table start (the line beginning with the first |) and one
blank line immediately after the table end (after the last | row) for each
Inputs and Outputs table in the document so they comply with MD058.
In @docs/content/platform/blocks/notion/read_database.md:
- Around line 30-31: The documentation table types for the Notion read_database
block are wrong: change the output types for "entries" and "entry" to match the
implementation by using List[Dict[str, Any]] for entries and Dict[str, Any] for
entry; update the table rows that currently show List[Dict[str, True]] and
Dict[str, True] so they reflect List[Dict[str, Any]] and Dict[str, Any],
respectively, matching the types used in the read_database block (entries and
entry variables).
In @docs/content/platform/blocks/smartlead/campaign.md:
- Around line 1-3: The generated block docs violate markdown heading hierarchy
because generate_block_markdown() hardcodes subsection headings as "###"; update
generate_block_markdown() (the function that builds lines at the points
currently adding "### What it is", "### What it does", "### How it works", "###
Inputs", "### Outputs", and "### Possible use case") to use "##" for those
subsection strings instead, then rerun the documentation generation to
regenerate all block markdown files so the change applies across the affected
files.
In @docs/content/platform/blocks/system/store_operations.md:
- Line 66: The table row for the "sort_by" column contains pipe characters
inside the cell value which are being interpreted as column delimiters; update
the "sort_by" cell value to remove internal pipes (e.g., use commas or the word
"or" like "rating, runs, name" or "rating or runs or name") so the row only has
the intended four columns and the table renders correctly.
| ### Inputs | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | query | Search query to find relevant code snippets. Describe what you're trying to do or what code you're looking for. | str | Yes | | ||
| | tokens_num | Token limit for response. Use 'dynamic' for automatic sizing, 5000 for standard queries, or 10000 for comprehensive examples. | str | int | No | | ||
|
|
There was a problem hiding this comment.
Fix table column count mismatch on tokens_num input row.
Line 20 has 5 cells instead of 4. The type specification str | int is incorrectly split across two separate cells. This should be a single Type cell containing the union type.
🔧 Proposed fix for tokens_num row
-| tokens_num | Token limit for response. Use 'dynamic' for automatic sizing, 5000 for standard queries, or 10000 for comprehensive examples. | str | int | No |
+| tokens_num | Token limit for response. Use 'dynamic' for automatic sizing, 5000 for standard queries, or 10000 for comprehensive examples. | str \| int | No |Note: If Markdown tables don't support | in cells directly, escape it as \|.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Inputs | |
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | query | Search query to find relevant code snippets. Describe what you're trying to do or what code you're looking for. | str | Yes | | |
| | tokens_num | Token limit for response. Use 'dynamic' for automatic sizing, 5000 for standard queries, or 10000 for comprehensive examples. | str | int | No | | |
| ### Inputs | |
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | query | Search query to find relevant code snippets. Describe what you're trying to do or what code you're looking for. | str | Yes | | |
| | tokens_num | Token limit for response. Use 'dynamic' for automatic sizing, 5000 for standard queries, or 10000 for comprehensive examples. | str \| int | No | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
20-20: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/exa/code_context.md around lines 16 - 21, The
tokens_num row in the Markdown table has five cells because the type column was
split into two cells ("str" and "int"); fix the tokens_num row in
docs/content/platform/blocks/exa/code_context.md by merging those two cells into
a single Type cell with the union type (e.g., "str | int" or escaped "str \|
int" if pipes break the table) so the row has exactly four columns: Input,
Description, Type, Required.
| # Exa Contents | ||
|
|
||
| ### What it is |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Read the file in question
cat -n docs/content/platform/blocks/exa/contents.md | head -40Repository: Significant-Gravitas/AutoGPT
Length of output: 2540
🏁 Script executed:
# Check if the generator script exists
find . -name "generate_block_docs.py" -o -name "*generate*" | grep -E "\.(py|js)$" | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 419
🏁 Script executed:
# Check other block documentation files to see if this is a pattern
ls -la docs/content/platform/blocks/*/Repository: Significant-Gravitas/AutoGPT
Length of output: 11988
🏁 Script executed:
# Look for markdown linting configuration
find . -name ".markdownlintrc*" -o -name "markdownlint*" | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 54
🏁 Script executed:
# Read the generator script to understand heading structure
cat autogpt_platform/backend/scripts/generate_block_docs.py | head -150Repository: Significant-Gravitas/AutoGPT
Length of output: 4182
🏁 Script executed:
# Check heading structure in other exa block files
for file in docs/content/platform/blocks/exa/*.md; do
echo "=== $(basename $file) ==="
head -5 "$file"
doneRepository: Significant-Gravitas/AutoGPT
Length of output: 1772
🏁 Script executed:
# Check heading structure in files from other blocks to see if pattern is systemic
for dir in docs/content/platform/blocks/apollo docs/content/platform/blocks/airtable; do
for file in $dir/*.md; do
echo "=== $(basename $file) ==="
head -5 "$file"
done | head -30
doneRepository: Significant-Gravitas/AutoGPT
Length of output: 779
🏁 Script executed:
# Search for markdown template generation in the generator script
cat autogpt_platform/backend/scripts/generate_block_docs.py | grep -A 10 -B 5 "###\|heading\|# " | head -100Repository: Significant-Gravitas/AutoGPT
Length of output: 2796
🏁 Script executed:
# Look for the full template generation section
cat autogpt_platform/backend/scripts/generate_block_docs.py | tail -300 | head -150Repository: Significant-Gravitas/AutoGPT
Length of output: 5046
🏁 Script executed:
# Check if there's a test file that shows expected output structure
cat autogpt_platform/backend/scripts/test_generate_block_docs.py | head -100Repository: Significant-Gravitas/AutoGPT
Length of output: 3113
🏁 Script executed:
# Find the actual markdown generation function
cat autogpt_platform/backend/scripts/generate_block_docs.py | grep -A 50 "def generate_block_markdown"Repository: Significant-Gravitas/AutoGPT
Length of output: 1854
🏁 Script executed:
# Search for where the h1 and h3 are being generated
cat autogpt_platform/backend/scripts/generate_block_docs.py | grep -n "^#\|^\s*#" | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 944
Fix markdown heading hierarchy in the documentation generator.
The heading hierarchy violation exists in autogpt_platform/backend/scripts/generate_block_docs.py. The generate_block_markdown function generates a top-level h1 heading for the block name, but then hardcodes h3 headings for subsections ("### What it is", "### What it does", etc.), which skips the h2 level and violates markdown formatting guidelines (MD001).
When is_first_in_file=True, the generator should use h2 for subsections; when is_first_in_file=False, it should use h3. This affects all generated block documentation files in docs/content/platform/blocks/.
🧰 Tools
🪛 LanguageTool
[grammar] ~1-~1: Ensure spelling is correct
Context: # Exa Contents ### What it is Retrieves docu...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/exa/contents.md around lines 1 - 3, The
generator generate_block_markdown currently hardcodes "###" for subsections
causing an MD001 heading hierarchy violation; modify generate_block_markdown to
compute a subsection prefix (use "##" when is_first_in_file is True, otherwise
"###") and use that prefix for all subsection headings ("What it is", "What it
does", etc.) instead of the hardcoded "###", ensuring generated files in
docs/content/platform/blocks/ use h2 subsections for the first file and h3
otherwise.
| ### Inputs | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | instructions | Research instructions - clearly define what information to find, how to conduct research, and desired output format. | str | Yes | | ||
| | model | Research model: 'fast' for quick results, 'standard' for balanced quality, 'pro' for thorough analysis | "exa-research-fast" | "exa-research" | "exa-research-pro" | No | | ||
| | output_schema | JSON Schema to enforce structured output. When provided, results are validated and returned as parsed JSON. | Dict[str, True] | No | | ||
| | wait_for_completion | Wait for research to complete before returning. Ensures you get results immediately. | bool | No | | ||
| | polling_timeout | Maximum time to wait for completion in seconds (only if wait_for_completion is True) | int | No | | ||
|
|
There was a problem hiding this comment.
Fix table column count mismatch on model input row (line 20).
The model row has 6 cells instead of 4. The enum values are listed in the Type column but are split across multiple cells. Consolidate the type into a single cell, escaped if necessary.
🔧 Proposed fix
-| model | Research model: 'fast' for quick results, 'standard' for balanced quality, 'pro' for thorough analysis | "exa-research-fast" | "exa-research" | "exa-research-pro" | No |
+| model | Research model: 'fast' for quick results, 'standard' for balanced quality, 'pro' for thorough analysis | "exa-research-fast" \| "exa-research" \| "exa-research-pro" | No |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ### Inputs | |
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | instructions | Research instructions - clearly define what information to find, how to conduct research, and desired output format. | str | Yes | | |
| | model | Research model: 'fast' for quick results, 'standard' for balanced quality, 'pro' for thorough analysis | "exa-research-fast" | "exa-research" | "exa-research-pro" | No | | |
| | output_schema | JSON Schema to enforce structured output. When provided, results are validated and returned as parsed JSON. | Dict[str, True] | No | | |
| | wait_for_completion | Wait for research to complete before returning. Ensures you get results immediately. | bool | No | | |
| | polling_timeout | Maximum time to wait for completion in seconds (only if wait_for_completion is True) | int | No | | |
| ### Inputs | |
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | instructions | Research instructions - clearly define what information to find, how to conduct research, and desired output format. | str | Yes | | |
| | model | Research model: 'fast' for quick results, 'standard' for balanced quality, 'pro' for thorough analysis | "exa-research-fast" \| "exa-research" \| "exa-research-pro" | No | | |
| | output_schema | JSON Schema to enforce structured output. When provided, results are validated and returned as parsed JSON. | Dict[str, True] | No | | |
| | wait_for_completion | Wait for research to complete before returning. Ensures you get results immediately. | bool | No | | |
| | polling_timeout | Maximum time to wait for completion in seconds (only if wait_for_completion is True) | int | No | | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
23-23: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/exa/research.md around lines 16 - 24, The
"model" input row in the Inputs table has too many cells; collapse the enum/type
values into the single Type cell for the "model" row (the row starting with
"model") so the table has four columns again, ensuring values like
"exa-research-fast", "exa-research", and "exa-research-pro" are combined in that
Type cell and any pipe characters are escaped or the cell quoted to avoid
splitting; keep the Required column as "No" and preserve the Description text in
its own cell.
| | event_type | Type of event that occurred | str | | ||
| | event_id | Unique identifier for this event | str | | ||
| | webset_id | ID of the affected webset | str | | ||
| | data | Event-specific data | Dict[str, True] | |
There was a problem hiding this comment.
Invalid type annotation: Dict[str, True] should be Dict[str, Any] or a proper generic type.
The output metadata field on line 29 uses Dict[str, True], which is not valid Python type syntax (True is a boolean value, not a type). This should be Dict[str, Any] or a more specific generic type. If this is auto-generated, check the generator script (scripts/generate_block_docs.py).
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/exa/webhook_blocks.md at line 29, The table row
for the metadata/data field currently shows an invalid type annotation
"Dict[str, True]"; update the type to a valid annotation such as "Dict[str,
Any]" (or a more specific generic) in the "metadata/data" entry in
docs/content/platform/blocks/exa/webhook_blocks.md, and if this doc is
auto-generated, fix the generator (scripts/generate_block_docs.py) to emit "Any"
(or the correct type) instead of the boolean literal True when producing
Dict[str, ...] annotations.
| | items_analyzed | Number of items analyzed | int | | ||
| | completion_percentage | Completion percentage (0-100) | int | | ||
| | elapsed_time | Total time elapsed in seconds | float | | ||
| | recall_info | Information about expected results and confidence | Dict[str, True] | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's check if the file exists and examine the relevant lines
fd -t f "websets_polling.md" --exec cat -n {} \;Repository: Significant-Gravitas/AutoGPT
Length of output: 6986
🏁 Script executed:
# Let's search for similar patterns in documentation files to understand the convention
rg "Dict\[str," docs/content/platform/blocks --type md -n | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 2729
🏁 Script executed:
# Also check for other type annotation patterns in similar documentation files
fd -t f "\.md$" docs/content/platform/blocks --exec grep -l "Dict\[" {} \;Repository: Significant-Gravitas/AutoGPT
Length of output: 3398
🏁 Script executed:
# Check if there's a generator or template file that creates these docs
fd -t f ".*webset.*" --exclude="*.md" | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 510
🏁 Script executed:
# Let's check if there's a generator script that creates these documentation files
fd -t f ".*\.py$" --path "*exa*" | grep -i "doc\|gen\|schema" | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 305
🏁 Script executed:
# Let's examine the actual Python block files to see what types they define
cat autogpt_platform/backend/backend/blocks/exa/websets_polling.py | head -200Repository: Significant-Gravitas/AutoGPT
Length of output: 7638
🏁 Script executed:
# Continue reading the Python file to see the full implementation
tail -n +180 autogpt_platform/backend/backend/blocks/exa/websets_polling.py | head -100Repository: Significant-Gravitas/AutoGPT
Length of output: 4470
🏁 Script executed:
# Let's also check what the _extract_search_progress and _extract_enrichment_progress methods return
grep -A 20 "_extract_search_progress\|_extract_enrichment_progress" autogpt_platform/backend/backend/blocks/exa/websets_polling.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 4583
🏁 Script executed:
# Let's check if there's a schema generator or documentation generation script
fd -t f "\.py$" | xargs grep -l "Dict\[str, True\]" | head -5Repository: Significant-Gravitas/AutoGPT
Length of output: 54
🏁 Script executed:
# Let's find the ExaWaitForSearchBlock to see what recall_info should be
grep -A 100 "class ExaWaitForSearchBlock" autogpt_platform/backend/backend/blocks/exa/websets_polling.py | grep -A 30 "class Output"Repository: Significant-Gravitas/AutoGPT
Length of output: 1480
🏁 Script executed:
# Check if there's a documentation generator script
fd -t f "\.py$" | xargs grep -l "websets_polling\|generate.*doc\|schema.*doc" | grep -v "__pycache__"Repository: Significant-Gravitas/AutoGPT
Length of output: 401
🏁 Script executed:
# Let's examine the documentation generation script
cat autogpt_platform/backend/scripts/generate_block_docs.py | head -300Repository: Significant-Gravitas/AutoGPT
Length of output: 9286
🏁 Script executed:
# Let's continue reading the type_to_readable function to understand how it generates types
tail -n +175 autogpt_platform/backend/scripts/generate_block_docs.py | head -50Repository: Significant-Gravitas/AutoGPT
Length of output: 1601
🏁 Script executed:
# Let's test what JSON schema Pydantic generates for a plain dict field
python3 << 'EOF'
from pydantic import BaseModel, Field
class TestModel(BaseModel):
recall_info: dict = Field(description="Test field")
schema = TestModel.model_json_schema()
print("Full schema:")
print(schema)
print("\nrecall_info field schema:")
print(schema['properties']['recall_info'])
EOFRepository: Significant-Gravitas/AutoGPT
Length of output: 158
🏁 Script executed:
# Let's check what type_to_readable returns for additionalProperties: true
python3 << 'EOF'
# Simulate what the type_to_readable function does
def type_to_readable(type_schema):
"""Simplified version of the generator function."""
if not isinstance(type_schema, dict):
return str(type_schema) if type_schema else "Any"
schema_type = type_schema.get("type")
if schema_type == "object":
if "additionalProperties" in type_schema:
value_type = type_to_readable(type_schema["additionalProperties"])
return f"Dict[str, {value_type}]"
title = type_schema.get("title", "Object")
return title
if schema_type == "boolean":
return "bool"
# Fallback
return type_schema.get("title", schema_type or "Any")
# Test case 1: object with additionalProperties as boolean true
test1 = {"type": "object", "additionalProperties": True}
print("additionalProperties: True =>", type_to_readable(test1))
# Test case 2: object with additionalProperties as boolean false
test2 = {"type": "object", "additionalProperties": False}
print("additionalProperties: False =>", type_to_readable(test2))
# Test case 3: dict type with no additionalProperties
test3 = {"type": "object"}
print("object with no additionalProperties =>", type_to_readable(test3))
EOFRepository: Significant-Gravitas/AutoGPT
Length of output: 209
🏁 Script executed:
# Let's verify the exact location and context of the bug in the generator
sed -n '155,195p' autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 1259
Fix the type annotation generator to handle boolean additionalProperties values.
The documentation generator (autogpt_platform/backend/scripts/generate_block_docs.py, lines 160-162) incorrectly converts plain dict type annotations to Dict[str, True]. When Pydantic generates JSON schema for a dict field, it sets additionalProperties: true (a boolean). The type_to_readable() function recursively processes this and converts the boolean True to the string "True", resulting in invalid syntax.
Update the generator to handle boolean additionalProperties values:
- When
additionalPropertiesisTrue(any additional properties allowed): convert to"Dict[str, Any]" - When
additionalPropertiesisFalse(no additional properties): convert to"Dict"or appropriate restriction
This bug affects documentation across multiple files (lines 81, 128, 129 in this file, plus similar issues in text.md, todoist/ files, and others).
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/exa/websets_polling.md at line 81, The
generator’s type_to_readable() currently treats a boolean additionalProperties
from Pydantic JSON schema as the literal string "True"; update
type_to_readable() in generate_block_docs.py to detect when
schema.get("additionalProperties") is a boolean: if True return "Dict[str, Any]"
(ensure Any is referenced/imported/mentioned in docs context) and if False
return "Dict" (or another concise restricted form) instead of converting the
boolean to a string; apply this change wherever type_to_readable() handles
dict/object schemas so generated docs no longer show Dict[str, True]/Dict[str,
False].
| # Add Audio To Video | ||
|
|
||
| ### What it is |
There was a problem hiding this comment.
Fix heading hierarchy to comply with MD001 (heading-increment).
The first block starts with h1 then jumps directly to h3, skipping h2. Subsequent blocks use h2→h3 hierarchy. Choose one consistent approach: either all blocks use h2 as the root level with h3 for subsections, or adjust the first block to match.
Recommended: use h2 for all block titles (Line 1, 41, 81) and h3 for subsections (What it is, What it does, etc.).
📝 Proposed fix for heading hierarchy
-# Add Audio To Video
+## Audio To Video
[no change needed for lines 41, 81]Also applies to: 41-43, 81-83
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/multimedia.md around lines 1 - 3, Change the
top-level heading "Add Audio To Video" from h1 to h2 so the file uses h2 for
block titles and h3 for subsections; specifically update the headings titled
"Add Audio To Video" (first occurrence and the other two occurrences referenced)
from "#" to "##" so they match the later blocks that use "### What it is"/"###
What it does" as subsections and restore a consistent h2→h3 hierarchy.
| ### Inputs | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | video_in | Video input (URL, data URI, or local path). | str (file) | Yes | | ||
| | audio_in | Audio input (URL, data URI, or local path). | str (file) | Yes | | ||
| | volume | Volume scale for the newly attached audio track (1.0 = original). | float | No | | ||
| | output_return_type | Return the final output as a relative path or base64 data URI. | "file_path" | "data_uri" | No | |
There was a problem hiding this comment.
Add blank lines around all tables to comply with MD058 (blanks-around-tables).
All 6 tables (Inputs and Outputs tables for each of the 3 blocks) are missing required blank lines before and after them. Add a blank line before the first line of each table and after the last line.
📝 Proposed fix for table spacing (example for Audio To Video block)
### Inputs
+
| Input | Description | Type | Required |
|-------|-------------|------|----------|
| video_in | Video input (URL, data URI, or local path). | str (file) | Yes |
| audio_in | Audio input (URL, data URI, or local path). | str (file) | Yes |
| volume | Volume scale for the newly attached audio track (1.0 = original). | float | No |
| output_return_type | Return the final output as a relative path or base64 data URI. | "file_path" | "data_uri" | No |
+
### OutputsApply the same pattern (blank line before and after each table) to all 6 tables in the document.
Also applies to: 25-28, 56-62, 65-68, 96-100, 103-106
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/multimedia.md around lines 16 - 22, All six
Markdown tables (the Inputs and Outputs tables under each block heading) are
missing required blank lines; add one blank line immediately before the table
start (the line beginning with the first |) and one blank line immediately after
the table end (after the last | row) for each Inputs and Outputs table in the
document so they comply with MD058.
| | entries | List of database entries with their properties. | List[Dict[str, True]] | | ||
| | entry | Individual database entry (yields one per entry found). | Dict[str, True] | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Find files related to read_database in the Notion blocks
find . -type f -name "*.py" -path "*/notion*" | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 572
🏁 Script executed:
# Search for the ReadDatabase class or read_database function
rg -l "read.*database" --type py -i | grep -i notion | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 135
🏁 Script executed:
# Search for Dict type hints in notion-related files
rg "Dict\[str,.*\]" --type py | grep -i notion | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 1333
🏁 Script executed:
# Examine the read_database.py file to see the full output schema definition
cat -n autogpt_platform/backend/backend/blocks/notion/read_database.py | head -80Repository: Significant-Gravitas/AutoGPT
Length of output: 3605
🏁 Script executed:
# Let's also check the documentation file to confirm the current incorrect type
cat -n docs/content/platform/blocks/notion/read_database.md | sed -n '28,35p'Repository: Significant-Gravitas/AutoGPT
Length of output: 623
Update type annotations in the output table.
The type annotations for entries and entry are incorrect. They should be List[Dict[str, Any]] and Dict[str, Any] respectively, matching the actual block implementation.
Current incorrect types:
| entries | List of database entries with their properties. | List[Dict[str, True]] |
| entry | Individual database entry (yields one per entry found). | Dict[str, True] |
The actual block code defines these as Dict[str, Any]:
- Line 54 in
autogpt_platform/backend/backend/blocks/notion/read_database.py:entries: List[Dict[str, Any]] - Line 57:
entry: Dict[str, Any]
Update the documentation to match the implemented types.
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/notion/read_database.md around lines 30 - 31,
The documentation table types for the Notion read_database block are wrong:
change the output types for "entries" and "entry" to match the implementation by
using List[Dict[str, Any]] for entries and Dict[str, Any] for entry; update the
table rows that currently show List[Dict[str, True]] and Dict[str, True] so they
reflect List[Dict[str, Any]] and Dict[str, Any], respectively, matching the
types used in the read_database block (entries and entry variables).
| # Add Lead To Campaign | ||
|
|
||
| ### What it is |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# Read the file to verify heading structure
cat -n docs/content/platform/blocks/smartlead/campaign.md | head -120Repository: Significant-Gravitas/AutoGPT
Length of output: 200
🏁 Script executed:
# Check if generation script exists and examine it
find . -name "generate_block_docs.py" -o -name "*generate*docs*" -type f | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 192
🏁 Script executed:
# Search for other block documentation files to understand the scope
fd -e md "blocks/.*\.md$" docs/ | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 54
🏁 Script executed:
# List files in repository to understand structure
git ls-files | grep -E "(campaign\.md|generate_block_docs)" | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 239
🏁 Script executed:
# Try to read the campaign.md file directly
git show HEAD:docs/content/platform/blocks/smartlead/campaign.md 2>/dev/null | head -150Repository: Significant-Gravitas/AutoGPT
Length of output: 4561
🏁 Script executed:
# Examine the generation script
cat -n ./autogpt_platform/backend/scripts/generate_block_docs.py | head -200Repository: Significant-Gravitas/AutoGPT
Length of output: 6987
🏁 Script executed:
# Find the markdown generation functions in the script
grep -n "###\|##\|heading\|markdown" ./autogpt_platform/backend/scripts/generate_block_docs.py | head -30Repository: Significant-Gravitas/AutoGPT
Length of output: 1280
🏁 Script executed:
# Read more of the generation script, focusing on markdown output
cat -n ./autogpt_platform/backend/scripts/generate_block_docs.py | sed -n '200,400p'Repository: Significant-Gravitas/AutoGPT
Length of output: 8666
🏁 Script executed:
# Check other block documentation files to see the pattern
fd -type f -name "*.md" docs/content/platform/blocks/ | head -5 | xargs -I {} sh -c 'echo "=== {} ===" && head -10 {}'Repository: Significant-Gravitas/AutoGPT
Length of output: 242
🏁 Script executed:
# Fix the fd command - search for markdown files in blocks directory correctly
find docs/content/platform/blocks -name "*.md" -type f | head -5 | xargs -I {} sh -c 'echo "=== {} ===" && head -10 {}'Repository: Significant-Gravitas/AutoGPT
Length of output: 3551
🏁 Script executed:
# Look at the full generate_block_markdown function to understand the logic
cat -n ./autogpt_platform/backend/scripts/generate_block_docs.py | sed -n '347,420p'Repository: Significant-Gravitas/AutoGPT
Length of output: 3217
🏁 Script executed:
# Verify the heading pattern across other block files - check subsection levels
find docs/content/platform/blocks -name "*.md" -type f ! -name "campaign.md" | head -10 | xargs -I {} sh -c 'echo "=== {} ===" && grep -E "^#{1,3} (What it is|What it does|How it works)" {}'Repository: Significant-Gravitas/AutoGPT
Length of output: 1161
🏁 Script executed:
# Count how many block files exist to understand scope
find docs/content/platform/blocks -name "*.md" -type f | wc -lRepository: Significant-Gravitas/AutoGPT
Length of output: 75
🏁 Script executed:
# Check if there's a markdown linting config file
find . -name ".markdownlint*" -o -name "markdownlint*" -type f 2>/dev/null | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 54
🏁 Script executed:
# Check git log for the generation script to see recent changes
git log --oneline -20 ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 162
🏁 Script executed:
# Check git log for smartlead/campaign.md to see if it's newly generated
git log --oneline -10 docs/content/platform/blocks/smartlead/campaign.mdRepository: Significant-Gravitas/AutoGPT
Length of output: 162
🏁 Script executed:
# Look at the actual current version to see heading levels one more time in campaign.md
grep -n "^#" docs/content/platform/blocks/smartlead/campaign.md | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 458
🏁 Script executed:
# Check git history of generate_block_docs.py more deeply to see if heading level changed
git log --all --oneline -- ./autogpt_platform/backend/scripts/generate_block_docs.py | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 162
🏁 Script executed:
# Look for when h2 vs h3 pattern emerged - check a few other recently modified block files
git log --oneline -5 docs/content/platform/blocks/ai_condition.md
git log --oneline -5 docs/content/platform/blocks/discord.mdRepository: Significant-Gravitas/AutoGPT
Length of output: 253
🏁 Script executed:
# Check the actual code in discord.md which showed h3 - verify it really uses h3
head -50 docs/content/platform/blocks/discord.md | grep -E "^#{1,4}"Repository: Significant-Gravitas/AutoGPT
Length of output: 286
🏁 Script executed:
# Check all block files to see the pattern of first block heading vs subsection heading
for file in $(find docs/content/platform/blocks -name "*.md" -type f | sort); do
first_block=$(head -20 "$file" | grep -E "^#{1,3} " | head -1)
first_subsection=$(head -20 "$file" | grep -E "^### What it is" | head -1)
if [ ! -z "$first_subsection" ]; then
echo "FILE: $file"
echo " First block: $first_block"
echo " First subsection: $first_subsection"
fi
done | head -50Repository: Significant-Gravitas/AutoGPT
Length of output: 2242
🏁 Script executed:
# Better approach: check for h1 → h3 pattern specifically (the MD001 violation)
echo "Files with h1 → h3 pattern (MD001 violation):"
for file in $(find docs/content/platform/blocks -name "*.md" -type f); do
if head -10 "$file" | grep -q "^# " && head -10 "$file" | grep -q "^### "; then
echo "$file"
fi
doneRepository: Significant-Gravitas/AutoGPT
Length of output: 6336
🏁 Script executed:
# Check for all different patterns
echo "Pattern analysis:"
echo "=== h1 → h2 ==="
for file in $(find docs/content/platform/blocks -name "*.md" -type f); do
if head -10 "$file" | grep -q "^# " && head -10 "$file" | grep "^##[^#]" | head -1 | grep -q "^## What"; then
basename "$file"
fi
done | head -5
echo ""
echo "=== h1 → h3 (VIOLATION) ==="
for file in $(find docs/content/platform/blocks -name "*.md" -type f); do
if head -10 "$file" | grep -q "^# " && head -10 "$file" | grep "^### What" | head -1 > /dev/null; then
basename "$file"
fi
done | head -5Repository: Significant-Gravitas/AutoGPT
Length of output: 296
🏁 Script executed:
# Count exact number of files with h1 → h3 violation
for file in $(find docs/content/platform/blocks -name "*.md" -type f); do
if head -10 "$file" | grep -q "^# " && head -10 "$file" | grep "^### What" > /dev/null; then
echo "$file"
fi
done | wc -lRepository: Significant-Gravitas/AutoGPT
Length of output: 75
🏁 Script executed:
# Verify the generation script logic one more time - check what is_first_in_file means
cat -n ./autogpt_platform/backend/scripts/generate_block_docs.py | sed -n '580,620p'Repository: Significant-Gravitas/AutoGPT
Length of output: 1887
Fix heading hierarchy in the generation script—subsections should use h2 instead of h3.
The h1 → h3 heading jump violates MD001 (markdown heading hierarchy must increment by one level at a time). This issue affects 126 generated block documentation files, including this one where the first block uses # Add Lead To Campaign (h1) followed by ### What it is (h3).
The root cause is in scripts/generate_block_docs.py. The generate_block_markdown() function (lines 362, 370, 375, 387, 401, 411) hardcodes subsection levels as ### (h3). Change these to ## (h2) to maintain proper heading hierarchy:
Lines 362, 370, 375, 387, 401, 411:
- lines.append("### What it is") → lines.append("## What it is")
- lines.append("### What it does") → lines.append("## What it does")
- lines.append("### How it works") → lines.append("## How it works")
- lines.append("### Inputs") → lines.append("## Inputs")
- lines.append("### Outputs") → lines.append("## Outputs")
- lines.append("### Possible use case") → lines.append("## Possible use case")
Regenerate all block documentation after this fix to apply changes across all 126 affected files.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/smartlead/campaign.md around lines 1 - 3, The
generated block docs violate markdown heading hierarchy because
generate_block_markdown() hardcodes subsection headings as "###"; update
generate_block_markdown() (the function that builds lines at the points
currently adding "### What it is", "### What it does", "### How it works", "###
Inputs", "### Outputs", and "### Possible use case") to use "##" for those
subsection strings instead, then rerun the documentation generation to
regenerate all block markdown files so the change applies across the affected
files.
| |-------|-------------|------|----------| | ||
| | query | Search query to find agents | str | No | | ||
| | category | Filter by category | str | No | | ||
| | sort_by | How to sort the results | "rating" | "runs" | "name" | No | |
There was a problem hiding this comment.
Fix table column syntax error (MD056).
Line 66 contains pipe characters (|) in the sort_by value that are being parsed as table column delimiters, creating 6 columns instead of 4. This breaks table rendering. Use commas or conjunctions instead of pipes.
🐛 Proposed fix for table column parsing
-| sort_by | How to sort the results | "rating" | "runs" | "name" | No |
+| sort_by | How to sort the results | "rating", "runs", or "name" | No |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | sort_by | How to sort the results | "rating" | "runs" | "name" | No | | |
| | sort_by | How to sort the results | "rating", "runs", or "name" | No | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
66-66: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/system/store_operations.md at line 66, The
table row for the "sort_by" column contains pipe characters inside the cell
value which are being interpreted as column delimiters; update the "sort_by"
cell value to remove internal pipes (e.g., use commas or the word "or" like
"rating, runs, name" or "rating or runs or name") so the row only has the
intended four columns and the table renders correctly.
| desc = inp.description or "-" | ||
| # Escape pipes in description | ||
| desc = desc.replace("|", "\\|") | ||
| lines.append(f"| {inp.name} | {desc} | {inp.type_str} | {required} |") |
There was a problem hiding this comment.
Newlines in descriptions break markdown tables
Medium Severity
The generate_block_markdown function escapes pipe characters in descriptions but does not handle newline characters. When block input/output descriptions contain newlines, they're inserted directly into markdown table rows, breaking the table structure. The generated documentation files show blank lines mid-row which standard markdown parsers interpret as table termination. The description text needs newlines replaced with spaces or HTML <br> tags to preserve valid table formatting.
Additional Locations (1)
| desc = inp.description or "-" | ||
| # Escape pipes in description | ||
| desc = desc.replace("|", "\\|") | ||
| lines.append(f"| {inp.name} | {desc} | {inp.type_str} | {required} |") |
There was a problem hiding this comment.
Unescaped pipes in type strings break table columns
Medium Severity
The generate_block_markdown function escapes pipe characters in descriptions via desc.replace("|", "\\|"), but type_str is inserted into the table row without any escaping. The type_to_readable function returns strings containing unescaped pipes for enum types (e.g., "private" | "public" | "unlisted") and union types (e.g., str | int). These unescaped pipes are interpreted as table column separators, creating malformed rows with incorrect column counts. The generated docs show rows like | visibility | ... | "private" | "public" | "unlisted" | No | which has 6 columns instead of 4.
Additional Locations (1)
|
Thank you for this comprehensive PR adding a block documentation auto-generation system. The implementation looks well thought out with scripts for generating documentation, preserving manual content, and adding CI workflows to maintain documentation synchronization. What Looks Great
Improvement Needed
Questions
This is a valuable addition that will help keep block documentation accurate and up-to-date. Please address the checklist issue, and this should be ready to merge. |
|
Thank you for this comprehensive PR that adds block documentation auto-generation capabilities. The scripts and workflows you've created will significantly improve documentation consistency and quality. Areas for improvement:
The system you've built looks excellent and well-thought-out, with particularly nice features like manual content preservation and migrating existing content. The automated CI enforcement will help ensure documentation stays in sync with code. |
|
Thank you for this comprehensive PR that adds block documentation auto-generation. The system looks robust with support for introspection, manual content preservation, and CI workflows. However, there are a couple of issues with your PR submission:
The code changes themselves look well-structured and comprehensive, including:
Please update your PR description to address these formatting issues so we can proceed with merging. |
|
Thank you for this comprehensive PR that adds an automated block documentation generation system! This looks like a valuable addition that will help keep block documentation consistent and up-to-date. Missing PR ChecklistI notice that the PR checklist is completely unchecked. Since this PR adds substantial Python scripts (not just immaterial changes), the checklist needs to be completed. Please check off the relevant items, particularly:
Technical ReviewThe implementation looks well-structured:
The addition of manually-preserved sections with Please complete the checklist, and this PR should be ready for approval. |
| desc = inp.description or "-" | ||
| # Escape pipes in description | ||
| desc = desc.replace("|", "\\|") | ||
| lines.append(f"| {inp.name} | {desc} | {inp.type_str} | {required} |") |
There was a problem hiding this comment.
Enum type pipe characters break markdown table formatting
Medium Severity
The type_to_readable function generates enum types as "val1" | "val2" | "val3" with pipe characters. While descriptions are escaped with desc.replace("|", "\\|") before being added to markdown tables, inp.type_str is not escaped. This causes table rows to have more columns than the header, breaking the markdown table rendering. Visible in generated docs like airtable/schema.md where field_type row has 6 columns instead of 4.
Additional Locations (1)
|
This pull request has conflicts with the base branch, please resolve those so we can evaluate the pull request. |
github-actions
bot
added
the
conflicts
|
Thanks for this comprehensive PR that creates a block documentation auto-generation system! The implementation looks thorough with code introspection, manual content preservation, CI integration, and AI enhancement capabilities. However, there are some issues with the PR submission that need to be addressed:
Regarding the implementation itself, it looks excellent. I particularly like:
Please update your PR description to address the template requirements, and this should be good to go! |
There was a problem hiding this comment.
Actionable comments posted: 19
🤖 Fix all issues with AI agents
In @docs/content/platform/blocks/basic.md:
- Around line 1-3: The document starts with an h1 ("# Add Memory") and then
jumps to an h3 ("### What it is"), violating heading-increment rules; fix by
making the section headings consistent—either demote the top title to h2 ("##
Add Memory") and keep "### What it is" as-is, or promote "### What it is" to h2
("## What it is") and ensure all subsequent sections follow proper H2/H3
hierarchy; if this file is generated, update the generator template so it emits
matching heading levels (e.g., h1 title plus h2 sections or all h2 section-based
documents).
- Around line 17-22: Add a blank line before and after every markdown table in
the file (e.g., the table starting with "| Input | Description | Type | Required
|") so they comply with markdownlint MD058; if docs are generated, update the
generator template to emit an empty line before and after each table or add a
post-processing step that inserts a newline above and below table blocks, then
re-run generation and linting to verify the tables at the other listed blocks
also have surrounding blank lines.
- Around line 216-230: The Inputs markdown table is malformed: the header
declares 4 columns (Input | Description | Type | Required) but some rows
(notably the "value" and "base_64" rows) contain an extra pipe/cell causing
MD056; edit the Inputs table so every row has exactly 4 pipe-separated cells
matching the header (fix/remove the extra pipe in the "value" row and any other
rows, and ensure the header separator row (|---|---|---|---|) matches four
columns).
- Around line 99-111: The inputs table header declares four columns but some
rows (e.g., the 'entry' row) contain unescaped pipe characters or extra
separators in the Description cell, causing a column mismatch; update each input
row for 'list', 'entry', 'entries', and 'position' so they have exactly four
pipe-separated cells matching the header by escaping any '|' in descriptions (or
wrapping the description in code/span/HTML) and ensuring no stray '|' characters
remain, so the table parses correctly.
In @docs/content/platform/blocks/data.md:
- Around line 54-65: The markdown generator is inserting unescaped pipe
characters into table cells and missing blank lines before tables; update the
code around where type_str is constructed (the place that uses inp.type_str /
out.type_str and the type_to_readable() output) to replace pipe characters with
escaped pipes (e.g., set type_str = inp.type_str.replace("|", "\\|") and do the
same for outputs) the same way desc is escaped, and ensure a blank line is
emitted before each table start (add a newline before the "Inputs" and "Outputs"
table generation points so there is an empty line between the heading and the
table).
In @docs/content/platform/blocks/github/issues.md:
- Line 1: The documentation uses the incorrect capitalization "Github" instead
of "GitHub" across this generated file; update the generator script
scripts/generate_block_docs.py to replace occurrences of "Github" with "GitHub"
(titles and inline references) so regenerated docs use the correct spelling,
then regenerate docs to correct all instances in
docs/content/platform/blocks/github/issues.md (and other generated files);
search for the literal "Github" in the generator templates or formatting
functions and change them to "GitHub" to ensure the correction applies to the
ten blocks listed.
In @docs/content/platform/blocks/google/gmail.md:
- Line 56: Several tables have rows with extra pipe separators because the
content_type field's enum/options were split across multiple cells; for each
affected section (Gmail Create Draft, Gmail Draft Reply, Gmail Forward, Gmail
Reply, Gmail Send) locate the content_type input row and collapse its Type cell
into a single cell (e.g., "auto, plain, html" or a single quoted value) and, if
needed, move the individual option descriptions into the Description cell so the
row matches the header's four columns (Input, Description, Type, Required);
ensure each row contains exactly four pipe-separated cells.
- Line 15: The markdown tables (e.g., the header row "| Input | Description |
Type | Required |") violate MD058 by lacking blank lines before and after them;
update the generator or the file to ensure every table block has one blank line
preceding and one blank line following the table (apply this fix to all tables
in the document, including the other instances flagged such as the repeating
table blocks), so every table is wrapped with empty lines to satisfy the lint
rule.
- Line 3: Add a top-level h2 heading for the block name before the existing "###
What it is" heading to fix the MD001 violation; for example insert "## Gmail"
(or the appropriate block title) as the first heading in the file so headings
increment by one level to the existing "### What it is".
In @docs/content/platform/blocks/google/sheets.md:
- Around line 1-14: Update the generator so block titles always use h2: in the
generator function that sets heading_level (the variable named heading_level
which currently depends on is_first_in_file), remove the conditional and set
heading_level to "##" unconditionally so all blocks use h2 and subsections
remain h3, ensuring consistent heading hierarchy.
In @docs/content/platform/blocks/llm.md:
- Line 604: The table row for the "voice_id" parameter currently uses the
generic link text "here"; update that link text to a descriptive phrase (e.g.,
"voice IDs and speaker options" or "list of voice IDs") so the cell reads: The
voice ID to use, get list of voices [voice IDs and speaker
options](https://docs.agpt.co/server/d_id) — change the anchor text only (leave
the URL intact) in the "voice_id" table entry.
- Line 402: Update the documentation for the generation_preset field: change the
phrase "only effects AI generated visuals" to the correct wording, e.g. "only
affects AI-generated visuals" (use "affects" as the verb and hyphenate
"AI-generated" as a compound adjective); the line to edit references the
generation_preset column in the table.
- Around line 1-3: The document uses an h1 for the title "AI Ad Maker Video
Creator" followed by h3 for the first subsection; change the subsection headings
so they increment by one level (use "## What it is" instead of "### What it is")
and apply the same h3→h2 conversion to all other section headers in this block
so every heading level advances by only one step.
- Around line 17-31: The Inputs and Outputs markdown tables are missing blank
lines before/after and the Inputs table has inconsistent column counts because
multi-value enum cells like the voice and background_music rows contain
unescaped pipe characters; update the doc generator to always emit a blank line
before and after each table, ensure each table row has the same number of cells
as the header (Input | Description | Type | Required), and format multi-value
enum cells by escaping or enclosing pipe characters (e.g., wrap the enum values
in backticks or replace pipes with an HTML entity like | or comma-separated
values) so they are treated as a single cell.
In @docs/content/platform/blocks/text.md:
- Around line 16-20: The generated markdown tables (e.g., the header row "|
Input | Description | Type | Required |") lack blank lines before and after the
table which violates MD058; update the table-emission logic (the code path that
renders table blocks / the function responsible for emitting table rows) to
always insert at least one blank line immediately before the header row and one
blank line after the final table row for every table produced (apply same change
for all occurrences listed). Ensure the change is applied in the
renderer/generator code that outputs the "| Input | Description | Type |
Required |" style table blocks so subsequent runs produce the required
surrounding blank lines.
- Line 147: Update the generated wording so compound adjectives are hyphenated:
change occurrences of case_sensitive / "case sensitive" to "case-sensitive"
(e.g., the table entry currently reading "case sensitive match" should read
"case-sensitive match") and change dot_all / "dot_all" or "dot all" to "dot-all"
(e.g., "dot-all option"). Locate and adjust the generation template or mapping
that emits the tokens case_sensitive and dot_all so they render with hyphens in
produced text.
- Around line 1-10: The document uses h3 ("###") for top-level block headings
(e.g., the "Code Extraction" title and the section headings "What it is", "What
it does", "How it works"), but the generator/template should emit h2 ("##") for
block-level sections; update the generator script or template that produces
these headings so it outputs "##" instead of "###" for those block-level
headings (adjust the template strings that render "Code Extraction" and the
"What it is"/"What it does"/"How it works" section headers).
- Around line 101-120: The Markdown tables for "Countdown Timer" inputs and "Get
Current Date" inputs contain unescaped union types like "int | str" which break
table cell parsing; update the docs generator to escape or reformat union types
(e.g., wrap union types in backticks like `int | str`, replace the pipe with a
safe separator such as "int / str" or "Union[int, str]", or HTML-escape the
pipe) so the type column remains a single cell; apply this change to how the
generator renders union types (affecting the "Countdown Timer" inputs table and
the "Get Current Date" inputs) so future runs produce valid 4-column rows.
🧹 Nitpick comments (4)
docs/content/platform/blocks/github/issues.md (1)
3-3: Fix markdown heading hierarchy and add blank lines around tables.The file has two markdown linting issues indicated by static analysis:
Heading levels (MD001): Section headings like "### What it is" should be "## What it is" since the block title is h1. Subsections should consistently use h2, not h3.
Blank lines around tables (MD058): Tables need blank lines immediately before and after them for proper markdown formatting and linter compliance.
These formatting issues likely originate in the generator script as well.
Example fix for the first block (lines 1–31)
# Github Add Label -### What it is +## What it is A block that adds a label to a GitHub issue or pull request. -### What it does +## What it does Allows users to add a specified label to an existing GitHub issue or pull request. -### How it works +## How it works <!-- MANUAL: how_it_works --> The block takes the GitHub credentials, the URL of the issue or pull request, and the label to be added as inputs. It then sends a request to the GitHub API to add the label to the specified issue or pull request. <!-- END MANUAL --> -### Inputs +## Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| | issue_url | URL of the GitHub issue or pull request | str | Yes | | label | Label to add to the issue or pull request | str | Yes | -### Outputs +## Outputs + | Output | Description | Type | |--------|-------------|------| | error | Error message if the label addition failed | str | | status | Status of the label addition operation | str | -### Possible use case +## Possible use case + <!-- MANUAL: use_case --> Automatically categorizing issues based on their content or assigning priority labels to newly created issues. <!-- END MANUAL -->Apply similar changes to all 10 blocks in this file.
Also applies to: 36-36, 67-67, 100-100, 139-139, 171-171, 204-204, 237-237, 269-269, 301-301
docs/content/platform/blocks/llm.md (1)
1-800: Review generator script to prevent future markdown linting failures.This auto-generated documentation file has systematic markdown formatting issues (heading hierarchy, table structure, blank lines, cell alignment). Before this PR merges, verify that the generator script (
scripts/generate_block_docs.py) produces valid, linted markdown. Runningmarkdownlintas part of the CI pipeline (as the PR'sdocs-block-sync.ymlworkflow suggests) will catch these issues automatically on future runs.As part of your test plan (requested by prior reviewers), confirm that:
- The generator produces valid markdown per
markdownlintrules- Running the generator on the codebase and validating against the CI lint step passes
- Generated tables properly format enum values (e.g., using proper markdown table escaping)
See the earlier verification script for linting validation.
docs/content/platform/blocks/google/sheets.md (1)
962-969: Minor language improvement in use case description.Line 966: "Add new records at specific positions" is slightly wordy. Consider "Insert records at specific positions" for conciseness.
This is a low-priority style note and may be auto-generated, so fixing in the generator template would be more efficient than manual edits.
docs/content/platform/blocks/data.md (1)
262-265: Minor compound adjective hyphenation.Line 265: "Whether to capture the full page length" — the compound adjective should be hyphenated: "full-page" instead of "full page". May be auto-generated, so fixing in the generator template would be more efficient.
📜 Review details
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Disabled knowledge base sources:
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (8)
docs/content/platform/blocks/basic.mddocs/content/platform/blocks/data.mddocs/content/platform/blocks/github/issues.mddocs/content/platform/blocks/google/gmail.mddocs/content/platform/blocks/google/sheets.mddocs/content/platform/blocks/jina/search.mddocs/content/platform/blocks/llm.mddocs/content/platform/blocks/text.md
🧰 Additional context used
🧠 Learnings (1)
📓 Common learnings
Learnt from: CR
Repo: Significant-Gravitas/AutoGPT PR: 0
File: .github/copilot-instructions.md:0-0
Timestamp: 2025-11-25T08:48:33.246Z
Learning: Applies to autogpt_platform/backend/backend/blocks/**/*.py : Agent blocks in backend/blocks/ must include: block definition with input/output schemas, execution logic with proper error handling, and tests validating functionality. Blocks inherit from Block base class with input/output schemas, implement run method, use uuid.uuid4() for block UUID, and be registered in block registry
🪛 LanguageTool
docs/content/platform/blocks/text.md
[grammar] ~147-~147: Use a hyphen to join words.
Context: ...act | int | No | | case_sensitive | Case sensitive match | bool | No | | dot_all ...
(QB_NEW_EN_HYPHEN)
[grammar] ~334-~334: Use a hyphen to join words.
Context: ...t | Data | Yes | | case_sensitive | Case sensitive match | bool | No | | dot_all ...
(QB_NEW_EN_HYPHEN)
docs/content/platform/blocks/basic.md
[style] ~102-~102: To form a complete sentence, be sure to include a subject.
Context: ...| entry | The entry to add to the list. Can be of any type (string, int, dict, etc....
(MISSING_IT_THERE)
[style] ~478-~478: It’s more common nowadays to write this noun as one word.
Context: ...se_case --> Name Collection: Gather user names, company names, or project names for pe...
(RECOMMENDED_COMPOUNDS)
docs/content/platform/blocks/llm.md
[uncategorized] ~402-~402: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... preset for visual style - only effects AI generated visuals | "Default" | "Anime" | "Realis...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/content/platform/blocks/github/issues.md
[uncategorized] ~1-~1: The official name of this software platform is spelled with a capital “H”.
Context: # Github Add Label ### What it is A block that ...
(GITHUB)
[grammar] ~68-~68: Ensure spelling is correct
Context: ...-- ## Github Comment ### What it is A block that posts comments on GitHub issues or...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/content/platform/blocks/data.md
[uncategorized] ~265-~265: If this is a compound adjective that modifies the following noun, use a hyphen.
Context: ... | | full_page | Whether to capture the full page length | bool | No | | format | Output ...
(EN_COMPOUND_ADJECTIVE_INTERNAL)
docs/content/platform/blocks/google/sheets.md
[style] ~966-~966: ‘new records’ might be wordy. Consider a shorter alternative.
Context: ... of lists. Ordered Data Entry: Add new records at specific positions to maintain sorti...
(EN_WORDINESS_PREMIUM_NEW_RECORDS)
🪛 markdownlint-cli2 (0.18.1)
docs/content/platform/blocks/text.md
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
22-22: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
68-68: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
74-74: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
102-102: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
105-105: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
106-106: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
107-107: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
108-108: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
112-112: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
142-142: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
152-152: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
181-181: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
188-188: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
216-216: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
219-219: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
223-223: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
255-255: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
261-261: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
293-293: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
299-299: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
329-329: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
338-338: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
367-367: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
372-372: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
404-404: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
411-411: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
443-443: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
450-450: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
482-482: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
487-487: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
docs/content/platform/blocks/basic.md
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
22-22: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
68-68: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
74-74: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
102-102: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
105-105: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
106-106: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
107-107: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
108-108: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
112-112: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
142-142: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
152-152: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
181-181: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
188-188: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
216-216: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
219-219: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
223-223: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
255-255: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
261-261: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
299-299: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
329-329: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
338-338: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
367-367: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
372-372: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
404-404: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
443-443: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
450-450: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
482-482: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
487-487: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
docs/content/platform/blocks/llm.md
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
22-22: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
23-23: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
28-28: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
60-60: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
66-66: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
69-69: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
101-101: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
105-105: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
110-110: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
139-139: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
142-142: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
144-144: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
145-145: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
148-148: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
180-180: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
184-184: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
186-186: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
189-189: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
221-221: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
224-224: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
225-225: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
225-225: Table column count
Expected: 4; Actual: 2; Too few cells, row will be missing data
(MD056, table-column-count)
225-225: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
234-234: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
264-264: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
268-268: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
275-275: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
305-305: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
308-308: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
314-314: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
315-315: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
318-318: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
350-350: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
356-356: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
357-357: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
360-360: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
392-392: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
394-394: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
394-394: Table column count
Expected: 4; Actual: 2; Too few cells, row will be missing data
(MD056, table-column-count)
408-408: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
438-438: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
443-443: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
454-454: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
457-457: Table column count
Expected: 3; Actual: 4; Too many cells, extra data will be missing
(MD056, table-column-count)
481-481: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
484-484: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
492-492: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
519-519: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
522-522: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
524-524: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
530-530: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
559-559: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
564-564: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
568-568: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
600-600: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
603-603: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
604-604: Link text should be descriptive
(MD059, descriptive-link-text)
607-607: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
608-608: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
615-615: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
643-643: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
646-646: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
647-647: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
648-648: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
649-649: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
651-651: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
653-653: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
657-657: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
689-689: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
692-692: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
697-697: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
730-730: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
733-733: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
746-746: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
780-780: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
786-786: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
docs/content/platform/blocks/google/gmail.md
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
15-15: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
21-21: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
49-49: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
56-56: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
60-60: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
92-92: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
102-102: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
106-106: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
141-141: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
150-150: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
154-154: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
188-188: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
220-220: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
225-225: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
255-255: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
281-281: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
287-287: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
314-314: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
320-320: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
348-348: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
358-358: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
362-362: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
395-395: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
402-402: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
406-406: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
docs/content/platform/blocks/github/issues.md
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
15-15: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
21-21: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
47-47: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
53-53: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
79-79: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
85-85: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
114-114: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
119-119: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
150-150: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
155-155: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
182-182: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
189-189: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
216-216: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
221-221: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
249-249: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
255-255: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
281-281: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
287-287: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
315-315: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
323-323: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
docs/content/platform/blocks/data.md
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
22-22: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
54-54: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
61-61: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
93-93: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
103-103: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
135-135: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
139-139: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
142-142: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
174-174: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
188-188: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
221-221: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
224-224: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
228-228: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
260-260: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
266-266: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
273-273: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
docs/content/platform/blocks/google/sheets.md
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
22-22: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
23-23: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
28-28: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
60-60: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
66-66: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
69-69: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
101-101: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
105-105: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
110-110: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
139-139: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
142-142: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
144-144: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
145-145: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
148-148: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
180-180: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
184-184: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
186-186: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
189-189: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
221-221: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
224-224: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
225-225: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
225-225: Table column count
Expected: 4; Actual: 2; Too few cells, row will be missing data
(MD056, table-column-count)
225-225: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
234-234: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
264-264: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
268-268: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
275-275: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
305-305: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
308-308: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
314-314: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
315-315: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
318-318: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
350-350: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
356-356: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
357-357: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
360-360: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
392-392: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
394-394: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
394-394: Table column count
Expected: 4; Actual: 2; Too few cells, row will be missing data
(MD056, table-column-count)
408-408: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
438-438: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
443-443: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
454-454: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
457-457: Table column count
Expected: 3; Actual: 4; Too many cells, extra data will be missing
(MD056, table-column-count)
481-481: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
484-484: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
492-492: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
519-519: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
522-522: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
524-524: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
530-530: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
559-559: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
564-564: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
568-568: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
600-600: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
603-603: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
604-604: Link text should be descriptive
(MD059, descriptive-link-text)
607-607: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
608-608: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
615-615: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
643-643: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
646-646: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
647-647: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
648-648: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
649-649: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
651-651: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
653-653: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
657-657: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
689-689: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
692-692: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
697-697: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
730-730: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
733-733: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
746-746: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
780-780: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
786-786: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
docs/content/platform/blocks/jina/search.md
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
15-15: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
21-21: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
47-47: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
52-52: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: Cursor Bugbot
- GitHub Check: Seer Code Review
🔇 Additional comments (6)
docs/content/platform/blocks/basic.md (1)
1-1450: Verify generated documentation compliance with CI linting rules.This file is auto-generated per the PR objectives. The systematic nature of heading and table formatting issues suggests they originate from the generator template. Before final approval, confirm:
- Whether markdownlint is enforced in the docs-block-sync.yml CI workflow.
- Whether the generator (scripts/generate_block_docs.py) produces output that complies with MD001, MD056, and MD058 rules.
- Whether post-generation fixes have been applied (as mentioned in PR comments about cleanup).
If linting compliance is required (likely, given the PR adds CI workflows for docs), regenerate the documentation and verify no markdownlint violations remain.
docs/content/platform/blocks/google/gmail.md (1)
1-416: The review comment is based on an incorrect assumption about the CI workflow. Thedocs-block-sync.ymlworkflow does not perform markdown linting validation—it only checks whether the block documentation is in sync with code changes using the--checkflag ofgenerate_block_docs.py. No markdownlint configuration or invocation exists in the CI pipelines, and the documentation generator itself does not enforce linting rules. Therefore, any markdown style variations in the documentation will not cause CI failures.Likely an incorrect or invalid review comment.
docs/content/platform/blocks/jina/search.md (2)
10-12: MANUAL marker structure is appropriate.The MANUAL comment blocks are consistently applied to editable sections (how_it_works, use_case) and should preserve user content across regenerations correctly.
Ensure the migration script tested in the PR correctly extracts and restores these sections during doc regeneration cycles.
Also applies to: 27-29, 42-44, 57-60
14-18: The Markdown formatting in this file is already correct. Tables at all mentioned locations (lines 15–18, 21–24, 47–49, 52–55) already have blank lines both before and after them per Markdown conventions. The templategenerate_block_docs.pycorrectly emitslines.append("")after each table (around lines 506 and 515 in the generator), which produces the required spacing. No action needed.docs/content/platform/blocks/google/sheets.md (1)
16-33: The markdown table formatting in this file is correctly generated and has no violations.The generator script (
generate_block_docs.py) explicitly adds blank lines before and after each table and maintains consistent column counts. The input tables have 4 columns throughout (lines 388-395), output tables have 3 columns (lines 402-407), and pipe characters are properly escaped in descriptions. No MD058, MD056, or MD055 violations exist.Likely an incorrect or invalid review comment.
docs/content/platform/blocks/data.md (1)
1-14: Markdown heading hierarchy issue — only affects the first block.The document violates heading hierarchy (MD001) only at lines 1-14, where the first block jumps from h1 ("# Create Dictionary") to h3 ("### What it is"), skipping h2. All subsequent blocks (starting at line 38) correctly use h2 for the block title and h3 for subsections.
The generator script always uses h3 for subsections but varies the block heading level based on position (
#for first,##for others). This works for all blocks except the first, which needs h2→h3 hierarchy to comply with markdown standards.Likely an incorrect or invalid review comment.
| # Add Memory | ||
|
|
||
| ## Store Value | ||
| ### What it is |
There was a problem hiding this comment.
Markdown heading hierarchy violation at document start.
The file begins with an h1 heading (# Add Memory) and immediately jumps to h3 (### What it is), skipping h2. This violates markdownlint rule MD001 (heading-increment). Consider either starting with h2 for each block section, or restructuring the document with an h1 title followed by h2 blocks.
Since this appears to be auto-generated, verify the generator template and adjust the heading levels accordingly.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/basic.md around lines 1 - 3, The document
starts with an h1 ("# Add Memory") and then jumps to an h3 ("### What it is"),
violating heading-increment rules; fix by making the section headings
consistent—either demote the top title to h2 ("## Add Memory") and keep "###
What it is" as-is, or promote "### What it is" to h2 ("## What it is") and
ensure all subsequent sections follow proper H2/H3 hierarchy; if this file is
generated, update the generator template so it emits matching heading levels
(e.g., h1 title plus h2 sections or all h2 section-based documents).
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | content | Content to add - either a string or list of message objects as output from an AI block | Content | No | | ||
| | metadata | Optional metadata for the memory | Dict[str, True] | No | | ||
| | limit_memory_to_run | Limit the memory to the run | bool | No | | ||
| | limit_memory_to_agent | Limit the memory to the agent | bool | No | |
There was a problem hiding this comment.
Tables missing blank lines before/after (markdownlint MD058).
Multiple input/output tables throughout the file lack blank lines before and after them. Markdown best practices and markdownlint rule MD058 require blank lines surrounding tables. This is a systematic issue affecting nearly all block documentation sections.
If this file is auto-generated, update the generator template to insert blank lines before/after each table. Alternatively, run a post-processing step to add these gaps during doc generation.
Also applies to: 68-74, 102-112, 142-152, 181-188, 216-223, 255-261, 299-304, 329-338, 367-372, 404-409, 443-450, 482-487
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
22-22: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/basic.md around lines 17 - 22, Add a blank line
before and after every markdown table in the file (e.g., the table starting with
"| Input | Description | Type | Required |") so they comply with markdownlint
MD058; if docs are generated, update the generator template to emit an empty
line before and after each table or add a post-processing step that inserts a
newline above and below table blocks, then re-run generation and linting to
verify the tables at the other listed blocks also have surrounding blank lines.
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | list | The list to add the entry to. If not provided, a new list will be created. | List[Any] | No | | ||
| | entry | The entry to add to the list. Can be of any type (string, int, dict, etc.). | Entry | No | | ||
| | entries | The entries to add to the list. This is the batch version of the `entry` field. | List[Any] | No | | ||
| | position | The position to insert the new entry. If not provided, the entry will be appended to the end of the list. | int | No | | ||
|
|
||
| ### Outputs | ||
| | Output | Description | Type | | ||
| |--------|-------------|------| | ||
| | error | Error message if the operation failed | str | | ||
| | updated_list | The list with the new entry added. | List[Any] | | ||
|
|
There was a problem hiding this comment.
Table column count mismatch in Add To List Inputs (MD056).
Lines 99–104 declare 4 columns (| Input | Description | Type | Required |) but row cells exceed that count. For example, line 102 has 5 cells: | entry | The entry to add to the list. Can be of any type (string, int, dict, etc.). | Entry | No | — the description contains commas/pipes that may be parsed as extra columns.
Verify table structure is correct and matches column count.
🧰 Tools
🪛 LanguageTool
[style] ~102-~102: To form a complete sentence, be sure to include a subject.
Context: ...| entry | The entry to add to the list. Can be of any type (string, int, dict, etc....
(MISSING_IT_THERE)
🪛 markdownlint-cli2 (0.18.1)
102-102: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
105-105: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
106-106: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
107-107: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
108-108: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/basic.md around lines 99 - 111, The inputs
table header declares four columns but some rows (e.g., the 'entry' row) contain
unescaped pipe characters or extra separators in the Description cell, causing a
column mismatch; update each input row for 'list', 'entry', 'entries', and
'position' so they have exactly four pipe-separated cells matching the header by
escaping any '|' in descriptions (or wrapping the description in code/span/HTML)
and ensuring no stray '|' characters remain, so the table parses correctly.
| This block provides a file upload input for users interacting with your agent. Users can upload files which are stored temporarily and passed to your workflow as a file path reference. | ||
|
|
||
| By default, the block outputs a file path string that other blocks can use to access the uploaded file. The optional base64 mode converts the file content to base64 encoding, though using file paths is generally recommended for better performance with large files. | ||
| <!-- END MANUAL --> | ||
|
|
||
| ### Inputs | ||
| | Input | Description | | ||
| |-------|-------------| | ||
| | Text | The text to be printed to the console | | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | name | The name of the input. | str | Yes | | ||
| | value | Path or reference to an uploaded file. | str (file) | No | | ||
| | title | The title of the input. | str | No | | ||
| | description | The description of the input. | str | No | | ||
| | advanced | Whether to show the input in the advanced section, if the field is not required. | bool | No | | ||
| | secret | Whether the input should be treated as a secret. | bool | No | | ||
| | base_64 | Whether produce an output in base64 format (not recommended, you can pass the string path just fine accross blocks). | bool | No | |
There was a problem hiding this comment.
Agent File Input table has inconsistent column structure (MD056).
The Inputs table (lines 216–230) shows 5 cells in some rows when header declares 4 columns. Line 219 appears to exceed the column count. Verify the table is well-formed.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
216-216: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
219-219: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
223-223: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/basic.md around lines 216 - 230, The Inputs
markdown table is malformed: the header declares 4 columns (Input | Description
| Type | Required) but some rows (notably the "value" and "base_64" rows)
contain an extra pipe/cell causing MD056; edit the Inputs table so every row has
exactly 4 pipe-separated cells matching the header (fix/remove the extra pipe in
the "value" row and any other rows, and ensure the header separator row
(|---|---|---|---|) matches four columns).
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | values | A list of values to be combined into a new list. | List[Any] | Yes | | ||
| | max_size | Maximum size of the list. If provided, the list will be yielded in chunks of this size. | int | No | | ||
| | max_tokens | Maximum tokens for the list. If provided, the list will be yielded in chunks that fit within this token limit. | int | No | | ||
|
|
||
| ### Outputs | ||
| | Output | Description | Type | | ||
| |--------|-------------|------| | ||
| | error | Error message if the operation failed | str | | ||
| | list | The created list containing the specified values. | List[Any] | | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n docs/content/platform/blocks/data.md | head -280Repository: Significant-Gravitas/AutoGPT
Length of output: 14730
🏁 Script executed:
# Check if sheets.md exists and has similar issues
if [ -f docs/content/platform/blocks/sheets.md ]; then
echo "=== Checking sheets.md for similar table formatting ==="
sed -n '135,145p' docs/content/platform/blocks/sheets.md
echo ""
echo "=== Checking for table formatting around lines with enum types ==="
rg -n "within_agent.*across_agents" docs/content/platform/blocks/sheets.md
else
echo "sheets.md not found"
fi
# Search for generator scripts
echo ""
echo "=== Searching for generator/build scripts ==="
find . -type f \( -name "*.py" -o -name "*.js" -o -name "*.sh" \) | xargs grep -l "data.md\|sheets.md" 2>/dev/null | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 138
🏁 Script executed:
# Search for generator scripts more broadly
echo "=== Searching for build/generation scripts ==="
find . -type f -name "*.py" | xargs grep -l "markdown\|\.md\|generate" 2>/dev/null | grep -E "(script|generate|build)" | head -15
# Look for block generation or documentation generation
echo ""
echo "=== Searching for block-related generation ==="
find . -type f -name "*.py" | xargs grep -l "block.*doc\|doc.*block" 2>/dev/null | head -10
# Check blocks directory structure
echo ""
echo "=== Checking blocks directory structure ==="
find docs/content/platform/blocks -type f | head -20
# Search for any markdown with table issues similar to data.md
echo ""
echo "=== Checking other markdown files in blocks directory for similar patterns ==="
rg -n "within_agent.*across_agents|scope.*persistence" docs/content/platform/blocks --type mdRepository: Significant-Gravitas/AutoGPT
Length of output: 2931
🏁 Script executed:
# Examine the generator script
echo "=== Checking generate_block_docs.py ==="
wc -l ./autogpt_platform/backend/scripts/generate_block_docs.py
echo ""
echo "=== Looking for table generation code ==="
sed -n '1,100p' ./autogpt_platform/backend/scripts/generate_block_docs.py
echo ""
echo "=== Searching for table/markdown generation patterns ==="
grep -n "table\|pipe\|markdown\|Type\|Description" ./autogpt_platform/backend/scripts/generate_block_docs.py | head -30Repository: Significant-Gravitas/AutoGPT
Length of output: 3762
🏁 Script executed:
# Look at the table generation code in detail
echo "=== Table generation code (lines 380-410) ==="
sed -n '380,410p' ./autogpt_platform/backend/scripts/generate_block_docs.py
echo ""
echo "=== Look for the escape_pipes function ==="
sed -n '1,100p' ./autogpt_platform/backend/scripts/generate_block_docs.py | grep -A 5 "escape"
echo ""
echo "=== Search for any escape/pipe handling functions ==="
grep -n "escape\|pipe" ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 1674
🏁 Script executed:
# Check the actual type_str values being generated
echo "=== Checking how type_str is extracted/generated ==="
sed -n '1,300p' ./autogpt_platform/backend/scripts/generate_block_docs.py | grep -B 5 -A 5 "type_str"
echo ""
echo "=== Check the FieldDoc and how type strings are processed ==="
sed -n '150,250p' ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 4809
🏁 Script executed:
# Look at the full type_to_readable function to see the enum handling
echo "=== Full type_to_readable function ==="
sed -n '100,180p' ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 2646
🏁 Script executed:
# Look at the exact table generation line and see if type_str is being escaped
echo "=== Lines 388-407 where tables are generated ==="
sed -n '385,410p' ./autogpt_platform/backend/scripts/generate_block_docs.py
echo ""
echo "=== Verify: Is type_str being escaped for pipes? ==="
grep -C 3 "type_str" ./autogpt_platform/backend/scripts/generate_block_docs.py | grep -A 5 "lines.append.*type_str"Repository: Significant-Gravitas/AutoGPT
Length of output: 1612
🏁 Script executed:
# Check if there are blank lines being added before tables
echo "=== Check for blank lines around tables in generator ==="
sed -n '380,415p' ./autogpt_platform/backend/scripts/generate_block_docs.py
echo ""
echo "=== Check what's before 'lines.append(\"### Inputs\")' ==="
sed -n '375,390p' ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 2281
Unescaped enum types in type_str creating extra table columns.
The generator script (./autogpt_platform/backend/scripts/generate_block_docs.py) has two issues:
-
MD056 violations (lines 139, 224, 266): Enum/union type descriptors are not escaped when inserted into table cells. Line 395 escapes
descbut nottype_str. Whentype_to_readable()generates types like"within_agent" | "across_agents", the unescaped pipe characters create extra columns instead of appearing as single cells. -
MD058 violations (lines 54, 61, 93, 103, etc.): No blank line between section headings (e.g.,
### Inputs) and table headers, violating markdown linting.
Fix in generate_block_docs.py:
- Line 395: Escape pipes in
type_strlike is done fordesc:type_str = inp.type_str.replace("|", "\\|") - Line 402: Same for outputs
- Lines 387-388 and 402-403: Add blank line before table start
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
54-54: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
61-61: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/data.md around lines 54 - 65, The markdown
generator is inserting unescaped pipe characters into table cells and missing
blank lines before tables; update the code around where type_str is constructed
(the place that uses inp.type_str / out.type_str and the type_to_readable()
output) to replace pipe characters with escaped pipes (e.g., set type_str =
inp.type_str.replace("|", "\\|") and do the same for outputs) the same way desc
is escaped, and ensure a blank line is emitted before each table start (add a
newline before the "Inputs" and "Outputs" table generation points so there is an
empty line between the heading and the table).
| |-------|-------------|------|----------| | ||
| | script_input | The text input for the script | str | Yes | | ||
| | provider | The voice provider to use | "microsoft" | "elevenlabs" | "amazon" | No | | ||
| | voice_id | The voice ID to use, get list of voices [here](https://docs.agpt.co/server/d_id) | str | No | |
There was a problem hiding this comment.
Use descriptive link text instead of bare "here".
Line 604 uses a generic "here" link. Replace with descriptive text like "voice IDs and speaker options" or similar to improve accessibility and clarity.
📝 Proposed fix
-| voice_id | The voice ID to use, get list of voices [here](https://docs.agpt.co/server/d_id) | str | No |
+| voice_id | The voice ID to use; see [available voices and speaker options](https://docs.agpt.co/server/d_id) | str | No |📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | voice_id | The voice ID to use, get list of voices [here](https://docs.agpt.co/server/d_id) | str | No | | |
| | voice_id | The voice ID to use; see [available voices and speaker options](https://docs.agpt.co/server/d_id) | str | No | |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
604-604: Link text should be descriptive
(MD059, descriptive-link-text)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/llm.md at line 604, The table row for the
"voice_id" parameter currently uses the generic link text "here"; update that
link text to a descriptive phrase (e.g., "voice IDs and speaker options" or
"list of voice IDs") so the cell reads: The voice ID to use, get list of voices
[voice IDs and speaker options](https://docs.agpt.co/server/d_id) — change the
anchor text only (leave the URL intact) in the "voice_id" table entry.
| ### Inputs | ||
| | Input | Description | | ||
| |-------|-------------| | ||
| | Text | The text to be matched against the pattern | | ||
| | Match | The pattern (regular expression) to search for in the text | | ||
| | Data | Additional information to be forwarded to the output | | ||
| | Case sensitive | Option to make the match case-sensitive or not | | ||
| | Dot all | Option to make the dot character match all characters, including newlines | | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | text | Text containing code blocks to extract (e.g., AI response) | str | Yes | | ||
|
|
There was a problem hiding this comment.
Add blank lines before and after all tables (MD058).
Tables throughout the document lack blank lines in the surrounding context. Markdown style requires blank lines immediately before and after table blocks. The generation script should emit blank lines (at least one blank line) before the | Input | Description |... header row and after the final data row of each table.
This is a style/linting requirement; the markdown will still render correctly without the blank lines, but the generated output should conform to the linting standard enforced in CI. Update the generator to insert blank lines between block sections and tables.
Also applies to: 68-72, 102-111, 142-150, 181-186, 216-221, 255-259, 293-297, 329-336, 367-370, 404-409, 443-448, 482-485
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
17-17: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/text.md around lines 16 - 20, The generated
markdown tables (e.g., the header row "| Input | Description | Type | Required
|") lack blank lines before and after the table which violates MD058; update the
table-emission logic (the code path that renders table blocks / the function
responsible for emitting table rows) to always insert at least one blank line
immediately before the header row and one blank line after the final table row
for every table produced (apply same change for all occurrences listed). Ensure
the change is applied in the renderer/generator code that outputs the "| Input |
Description | Type | Required |" style table blocks so subsequent runs produce
the required surrounding blank lines.
| ### Inputs | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | input_message | Message to output after the timer finishes | Input Message | No | | ||
| | seconds | Duration in seconds | int | str | No | | ||
| | minutes | Duration in minutes | int | str | No | | ||
| | hours | Duration in hours | int | str | No | | ||
| | days | Duration in days | int | str | No | | ||
| | repeat | Number of times to repeat the timer | int | No | | ||
|
|
||
| ### Outputs | ||
| | Output | Description | Type | | ||
| |--------|-------------|------| | ||
| | error | Error message if the operation failed | str | | ||
| | output_message | Message after the timer finishes | Output Message | | ||
|
|
||
| ### Possible use case | ||
| <!-- MANUAL: use_case --> | ||
| **Rate Limiting**: Add a delay between API calls to respect rate limits when processing large batches of data through external services. | ||
|
|
There was a problem hiding this comment.
Fix table column count errors caused by union type formatting (lines 105–108, 219).
Tables must have the same number of cells in every row. The "Countdown Timer" inputs table has a header with 4 columns but data rows (105–108) contain 5 cells, because the type column contains int | str where the pipe character (|) is interpreted as a column delimiter.
Similarly, line 219 ("Get Current Date" inputs) has the same issue with int | str types. Extra cells in a row are usually not shown, so their data is lost.
The generation script should escape or reformat union types to prevent pipes from being parsed as column separators. Consider using backticks (`int | str`) or a different separator (e.g., int / str or Union[int, str]).
🔧 Proposed fix: escape union types in table cells
Example fix for lines 105–108:
-| seconds | Duration in seconds | int | str | No |
-| minutes | Duration in minutes | int | str | No |
-| hours | Duration in hours | int | str | No |
-| days | Duration in days | int | str | No |
+| seconds | Duration in seconds | `int \| str` | No |
+| minutes | Duration in minutes | `int \| str` | No |
+| hours | Duration in hours | `int \| str` | No |
+| days | Duration in days | `int \| str` | No |Note: Update the generator script to escape pipes in union types or use a rendered-safe format.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
102-102: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
105-105: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
106-106: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
107-107: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
108-108: Table column count
Expected: 4; Actual: 5; Too many cells, extra data will be missing
(MD056, table-column-count)
112-112: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/text.md around lines 101 - 120, The Markdown
tables for "Countdown Timer" inputs and "Get Current Date" inputs contain
unescaped union types like "int | str" which break table cell parsing; update
the docs generator to escape or reformat union types (e.g., wrap union types in
backticks like `int | str`, replace the pipe with a safe separator such as "int
/ str" or "Union[int, str]", or HTML-escape the pipe) so the type column remains
a single cell; apply this change to how the generator renders union types
(affecting the "Countdown Timer" inputs table and the "Get Current Date" inputs)
so future runs produce valid 4-column rows.
| | text | Text to parse | Text | Yes | | ||
| | pattern | Pattern (Regex) to parse | str | Yes | | ||
| | group | Group number to extract | int | No | | ||
| | case_sensitive | Case sensitive match | bool | No | |
There was a problem hiding this comment.
Use hyphenated form for compound adjectives: "case-sensitive" and "dot-all".
Lines 147 and 334 use "case sensitive" and "dot_all" where grammar rules call for hyphenation when used as adjectives before nouns: "case-sensitive match" and "dot-all option".
The generation script should emit these terms in hyphenated form.
Also applies to: 334-334
🧰 Tools
🪛 LanguageTool
[grammar] ~147-~147: Use a hyphen to join words.
Context: ...act | int | No | | case_sensitive | Case sensitive match | bool | No | | dot_all ...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/text.md at line 147, Update the generated
wording so compound adjectives are hyphenated: change occurrences of
case_sensitive / "case sensitive" to "case-sensitive" (e.g., the table entry
currently reading "case sensitive match" should read "case-sensitive match") and
change dot_all / "dot_all" or "dot all" to "dot-all" (e.g., "dot-all option").
Locate and adjust the generation template or mapping that emits the tokens
case_sensitive and dot_all so they render with hyphens in produced text.
| # Try with class name | ||
| manual_content = manual_content_cache.get(block.class_name, {}) | ||
| if not manual_content: | ||
| missing_count += 1 |
There was a problem hiding this comment.
Statistics undercounted when class_name fallback succeeds
Low Severity
When manual content is found via block.name, preserved_count is incremented. However, when block.name lookup fails but the block.class_name fallback succeeds, neither counter is incremented. This causes the migration script to underreport the number of blocks with preserved content in its final statistics output.
| options.append(type_to_readable(opt)) | ||
| if len(options) == 1: | ||
| return options[0] | ||
| return " | ".join(options) |
There was a problem hiding this comment.
Empty type string when anyOf contains only null
Low Severity
The type_to_readable function filters out null types from anyOf unions to simplify display (e.g., str | None becomes str). However, if all options in anyOf are null types, the options list ends up empty, and " | ".join([]) returns an empty string "". This would produce an empty Type cell in the generated markdown documentation tables, which is confusing. The function lacks a fallback for when all options are filtered out.
There was a problem hiding this comment.
Actionable comments posted: 5
Note
Due to the large number of review comments, Critical severity comments were prioritized as inline comments.
🤖 Fix all issues with AI agents
In @docs/content/platform/blocks/apollo/organization.md:
- Around line 14-37: The Inputs table's cells contain unescaped multiline
content and a typo causing rendering issues; fix by converting multiline
descriptions into single-line cells (use <br> tags or join lines) for
organization_num_employees_range, organization_locations (merge the broken
sentence so "appear" replaces "appearch"), organizations_not_locations, and any
other wrapped descriptions, ensure the header/table has a blank line before and
after it, and verify column alignment for List[int]/List[str]/str/int types so
the markdown table renders correctly.
In @docs/content/platform/blocks/github/statuses.md:
- Around line 14-21: The Inputs table is rendered with union types split into
multiple markdown cells (see the `state` row and other fields like `sort_by`,
`language`, `output_format`, `sampling_method`), breaking the 4-column layout;
update the doc generator to treat union type values as a single table cell by
escaping pipe characters or wrapping the entire union in an inline code
span/HTML entity when generating the Type column so `"error" | "failure" |
"pending"` stays one cell and the table remains 4 columns (Input, Description,
Type, Required).
In @docs/content/platform/blocks/misc.md:
- Around line 239-241: Replace the inline curl example that includes the
"Authorization: Bearer YOUR_ACCESS_TOKEN" pattern with a secure example that
references an environment variable (e.g., $MEDIUM_ACCESS_TOKEN) or secret
manager usage instead of a literal token, remove the trailing stray quote in the
example, add a short warning line "Never include actual tokens in examples or
code", and append a pointer to the Medium API authentication docs for secure
token handling; update the table cell text for author_id to reference obtaining
the authorId via the /me endpoint without showing plaintext tokens.
In @docs/content/platform/blocks/system/store_operations.md:
- Around line 55-62: The table row for the sort_by input contains unescaped pipe
characters which split the cell into extra columns; update the sort_by row so
the type is a single cell by quoting or code-formatting the union (e.g., "rating
| runs | name" or `rating | runs | name`) or replacing pipes with HTML entity
| so the row becomes four cells: header, description, type, required; edit
the line containing sort_by to use one of these forms to restore proper markdown
table structure.
In @docs/content/platform/blocks/twitter/bookmark.md:
- Around line 1-3: The section headers in generate_block_markdown() are
hardcoded as h3 (###); change the function to compute section_heading_level =
heading_level + 1 and use that computed level when emitting all section headings
(e.g., "What it is", "Inputs", "Outputs", "Examples", etc.) instead of the
literal "###"; update every place in generate_block_markdown() that currently
injects "###" to use the derived section_heading_level so h1 blocks produce "##"
sections and h2 blocks produce "###" sections.
🟠 Major comments (39)
docs/content/platform/blocks/hubspot/company.md-17-17 (1)
17-17: Replace placeholder typeDict[str, True]with appropriate type annotation.Type annotations showing
Dict[str, True]are not valid—Trueis a boolean value, not a type. Should beDict[str, Any]or a more specific dict type if known.🔧 Proposed fix for type annotations
-| company_data | Company data for create/update operations | Dict[str, True] | No | +| company_data | Company data for create/update operations | Dict[str, Any] | No |And:
-| company | Company information | Dict[str, True] | +| company | Company information | Dict[str, Any] |Also applies to: 24-24
docs/content/platform/blocks/hubspot/contact.md-17-17 (1)
17-17: Replace placeholder typeDict[str, True]with appropriate type annotation.Type annotations showing
Dict[str, True]are not valid—Trueis a boolean value, not a type. Should beDict[str, Any]or a more specific dict type if known.🔧 Proposed fix for type annotations
-| contact_data | Contact data for create/update operations | Dict[str, True] | No | +| contact_data | Contact data for create/update operations | Dict[str, Any] | No |And:
-| contact | Contact information | Dict[str, True] | +| contact | Contact information | Dict[str, Any] |Also applies to: 24-24
docs/content/platform/blocks/hubspot/engagement.md-17-17 (1)
17-17: Replace placeholder typeDict[str, True]with appropriate type annotation.Type annotations showing
Dict[str, True]are not valid—Trueis a boolean value, not a type. Should beDict[str, Any]or a more specific dict type if known.🔧 Proposed fix for type annotations
-| email_data | Email data including recipient, subject, content | Dict[str, True] | No | +| email_data | Email data including recipient, subject, content | Dict[str, Any] | No |And:
-| result | Operation result | Dict[str, True] | +| result | Operation result | Dict[str, Any] |Also applies to: 25-25
docs/content/platform/blocks/discord/bot_blocks.md-20-20 (1)
20-20: Fix malformed table: missingauto_archive_durationtype and incomplete enum values.The
auto_archive_durationrow in the Inputs table is malformed with raw string values spanning multiple pipe delimiters, breaking the 4-column structure. Additionally, it lists only three of four valid enum values ("60","1440","4320") and omits"10080"(ONE_WEEK).Update the Type column to properly represent
ThreadArchiveDurationor list all four valid durations:"60","1440","4320","10080".docs/content/platform/blocks/generic_webhook/triggers.md-1-24 (1)
1-24: Fix heading level jumps + add blank lines around tables; also clarify the “generic input” sentence.Proposed fix
# Generic Webhook Trigger -### What it is -This block will output the contents of the generic input for the webhook. +## What it is +This block triggers on incoming webhook requests and outputs the received payload. -### How it works +## How it works <!-- MANUAL: how_it_works --> This block creates a webhook endpoint that receives and outputs any incoming HTTP payload. When external services send data to this webhook URL, the block triggers and outputs the complete payload as a dictionary. Constants can be configured to pass additional static values alongside the dynamic webhook data. <!-- END MANUAL --> -### Inputs +## Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| | constants | The constants to be set when the block is put on the graph | Dict[str, True] | No | -### Outputs +## Outputs + | Output | Description | Type | |--------|-------------|------| | error | Error message if the operation failed | str | | payload | The complete webhook payload that was received from the generic webhook. | Dict[str, True] | | constants | The constants to be set when the block is put on the graph | Dict[str, True] |docs/content/platform/blocks/twitter/search_spaces.md-1-49 (1)
1-49: Inputs/Outputs tables are malformed (multi-line cells + unescaped|), likely breaking rendering and lint.Proposed fix (keep content, make tables valid)
# Twitter Search Spaces -### What it is +## What it is This block searches for Twitter Spaces based on specified terms. -### How it works +## How it works <!-- MANUAL: how_it_works --> This block queries the Twitter API v2 to search for Twitter Spaces (live audio conversations) matching a search term. Results can be filtered by state (live, scheduled, or all) and include Space metadata like title, host information, and participant counts. The block uses Tweepy with OAuth 2.0 authentication and supports expansions to include additional data about creators, hosts, speakers, invited users, and topics. Returns paginated results with Space IDs, titles, and host information. <!-- END MANUAL --> -### Inputs +## Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| -| expansions | Choose additional information you want to get with your Twitter Spaces: -- Select 'Invited_Users' to see who was invited -- Select 'Speakers' to see who can speak -- Select 'Creator' to get details about who made the Space -- Select 'Hosts' to see who's hosting -- Select 'Topics' to see Space topics | SpaceExpansionsFilter | No | -| space_fields | Choose what Space details you want to see, such as: -- Title -- Start/End times -- Number of participants -- Language -- State (live/scheduled) -- And more | SpaceFieldsFilter | No | -| user_fields | Choose what user information you want to see. This works when you select any of these in expansions above: -- 'Creator' for Space creator details -- 'Hosts' for host information -- 'Speakers' for speaker details -- 'Invited_Users' for invited user information | TweetUserFieldsFilter | No | +| expansions | Choose additional information to include (Invited_Users, Speakers, Creator, Hosts, Topics). | SpaceExpansionsFilter | No | +| space_fields | Choose which Space fields to include (Title, Start/End times, participants, language, state, etc.). | SpaceFieldsFilter | No | +| user_fields | User fields to include when requesting user expansions (Creator, Hosts, Speakers, Invited_Users). | TweetUserFieldsFilter | No | | query | Search term to find in Space titles | str | Yes | | max_results | Maximum number of results to return (1-100) | int | No | -| state | Type of Spaces to return (live, scheduled, or all) | "live" | "scheduled" | "all" | No | +| state | Type of Spaces to return (live, scheduled, or all) | `"live" \| "scheduled" \| "all"` | No | -### Outputs +## Outputs + | Output | Description | Type | |--------|-------------|------| | error | Error message if the operation failed | str | | ids | List of space IDs | List[str] | | titles | List of space titles | List[str] | | host_ids | List of host IDs | List[Any] | | next_token | Next token for pagination | str | | data | Complete space data | List[Dict[str, True]] | | includes | Additional data requested via expansions | Dict[str, True] | | meta | Metadata including pagination info | Dict[str, True] |docs/content/platform/blocks/fal/ai_video_generator.md-1-25 (1)
1-25: Tables are invalid due to unescaped|in themodelrow; also fix heading levels + table spacing.Proposed fix
# AI Video Generator -### What it is +## What it is Generate videos using FAL AI models. -### How it works +## How it works <!-- MANUAL: how_it_works --> This block generates videos from text prompts using FAL.ai's video generation models including Mochi, Luma Dream Machine, and Veo3. Describe the video you want to create, and the AI generates it. The generated video URL is returned along with progress logs for monitoring longer generation jobs. <!-- END MANUAL --> -### Inputs +## Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| | prompt | Description of the video to generate. | str | Yes | -| model | The FAL model to use for video generation. | "fal-ai/mochi-v1" | "fal-ai/luma-dream-machine" | "fal-ai/veo3" | No | +| model | The FAL model to use for video generation. | `Literal["fal-ai/mochi-v1", "fal-ai/luma-dream-machine", "fal-ai/veo3"]` | No | -### Outputs +## Outputs + | Output | Description | Type | |--------|-------------|------| | error | Error message if video generation failed. | str | | video_url | The URL of the generated video. | str | | logs | Generation progress logs. | List[str] |docs/content/platform/blocks/compass/triggers.md-1-18 (1)
1-18: Fix heading level jumps and add blank lines around the Outputs table (markdownlint).
This currently violates MD001 and MD058.Proposed fix
# Compass AI Trigger -### What it is -This block will output the contents of the compass transcription. +## What it is +This block will output the contents of the Compass AI transcription. -### How it works +## How it works <!-- MANUAL: how_it_works --> This block triggers when a Compass AI transcription is received. It outputs the transcription text content, enabling workflows that process voice input or meeting transcripts from Compass AI. The transcription is output as a string for downstream processing, analysis, or storage. <!-- END MANUAL --> -### Outputs +## Outputs + | Output | Description | Type | |--------|-------------|------| | error | Error message if the operation failed | str | | transcription | The contents of the compass transcription. | str | -### Possible use case +## Possible use case <!-- MANUAL: use_case --> **Voice Command Processing**: Trigger workflows from voice commands transcribed by Compass AI. **Meeting Automation**: Process meeting transcripts to extract action items or summaries. **Transcription Analysis**: Analyze transcribed content for sentiment, topics, or key information. <!-- END MANUAL -->Committable suggestion skipped: line range outside the PR's diff.
docs/content/platform/blocks/jina/search.md-1-56 (1)
1-56: Fix heading level inconsistency between documentation blocks.The first block uses h1 heading with h3 subsections (skipping h2), while the second block correctly uses h2 with h3 subsections. This creates a document structure violation and inconsistency. Change the first block's heading from h1 to h2 to match the second block's structure.
Additionally, add blank lines before each table for proper Markdown formatting consistency.
Proposed fix
-# Extract Website Content +## Extract Website ContentAnd add blank lines before tables:
### How it works <!-- MANUAL: how_it_works --> The block sends a request to the given URL, downloads the HTML content, and uses content extraction algorithms to identify and extract the main text content of the page. <!-- END MANUAL --> + ### InputsCommittable suggestion skipped: line range outside the PR's diff.
docs/content/platform/blocks/twitter/mutes.md-1-110 (1)
1-110: Fix heading increment and table formatting.The first block uses h1 while subsections jump directly to h3 (line 1 vs line 3), breaking Markdown heading hierarchy. Additionally, tables lack blank lines between section headings and table content; each heading should have a blank line before the table marker.
🔧 Proposed fixes
Change the first block heading to h2 for consistency:
-# Twitter Get Muted Users +## Twitter Get Muted UsersAdd blank lines after all section headings that precede tables:
### Inputs + | Input | Description | Type | Required |Apply the same blank line addition after "### Outputs" headings (lines 22, 61, 95).
Committable suggestion skipped: line range outside the PR's diff.
docs/content/platform/blocks/smartlead/campaign.md-1-112 (1)
1-112: Fix heading increment, add blank lines before tables, and correct table column mismatch on line 101.Heading levels should increment by one level at a time. Line 1 uses h1, but lines 3 onwards jump to h3. Additionally, all six tables lack required blank lines before them. The "Save Campaign Sequences" Outputs table (lines 98–102) has a column count mismatch: the header declares 3 columns but line 101's data row contains 4 cells.
🔧 Proposed fixes
Fix heading on line 1:
-# Add Lead To Campaign +## Add Lead To CampaignAdd blank lines before all tables, e.g., before line 14:
### Inputs + | Input | Description | Type | Required |(Repeat for all tables at lines 14, 21, 56, 61, 92, and 98.)
Fix table on lines 98–102. The
datarow (line 101) has 4 cells but the header only declares 3 columns:### Outputs | Output | Description | Type | |--------|-------------|------| | error | Error message if the sequences were not saved | str | -| data | Data from the API | Dict[str, True] | str | +| data | Data from the API | Dict[str, True] | | message | Message from the API | str |Committable suggestion skipped: line range outside the PR's diff.
docs/content/platform/blocks/exa/websets_search.md-1-11 (1)
1-11: Fix heading hierarchy: use h2 for section headers, not h3.The document starts with an h1 heading (
# Exa Cancel Webset Search) and jumps directly to h3 (### What it is), skipping h2. This violates markdown spec (MD001). All subsections should use h2 (##).This issue affects the entire generated documentation set. Consider fixing the generator script to output h2 for section headers instead of h3.
🔧 Proposed fix for heading hierarchy
- ### What it is + ## What it is - ### How it works + ## How it works - ### Inputs + ## Inputs - ### Outputs + ## Outputs - ### Possible use case + ## Possible use caseApply this change consistently across all documentation files.
docs/content/platform/blocks/ayrshare/post_to_x.md-13-46 (1)
13-46: Add blank lines before and after tables (MD058).Tables on lines 14 and 42 are missing required blank lines before them. Markdown linters and renderers expect blank lines to separate block-level content.
🔧 Proposed fix
### Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| ... + ### Outputsdocs/content/platform/blocks/ayrshare/post_to_x.md-1-12 (1)
1-12: Fix markdown heading hierarchy across all Ayrshare block documentation: h1 must be followed by h2, not h3.All 13 documentation files in
docs/content/platform/blocks/ayrshare/follow the same problematic pattern:# Title(h1) jumps directly to### What it is(h3), skipping h2. This violates MD001 and breaks document outline/navigation.Change all section headings from h3 (
###) to h2 (##):🔧 Proposed fix for heading hierarchy
# Post To X - ### What it is + ## What it is Post to X / Twitter using Ayrshare - ### How it works + ## How it works <!-- MANUAL: how_it_works --> ... - ### Inputs + ## Inputs - ### Outputs + ## Outputs - ### Possible use case + ## Possible use caseApply this change to all 13 files:
post_to_bluesky.md,post_to_facebook.md,post_to_gmb.md,post_to_instagram.md,post_to_linkedin.md,post_to_pinterest.md,post_to_reddit.md,post_to_snapchat.md,post_to_telegram.md,post_to_threads.md,post_to_tiktok.md,post_to_x.md, andpost_to_youtube.md.Committable suggestion skipped: line range outside the PR's diff.
docs/content/platform/blocks/baas/bots.md-1-3 (1)
1-3: Change the first block heading from h1 to h2 for consistency across all blocks.Line 1 uses
#(h1) while all other block titles use##(h2), creating both a heading-level jump violation (h1 → h3 at line 3, violating MD001) and inconsistent structure across the file. The subsequent blocks (lines 35, 65, 111) all correctly use h2 main headings with h3 subsections. Update line 1 to## Baas Bot Delete Recordingto match this pattern.docs/content/platform/blocks/baas/bots.md-13-22 (1)
13-22: Add blank lines before all tables per MD058.Tables must be surrounded by blank lines both before and after (except at document boundaries). Currently, each table is immediately preceded by its heading (e.g.,
### Inputs) with no blank line in between. This violates the MD058 rule across all four blocks.Affected ranges: 13-22, 47-59, 84-95, 127-136
docs/content/platform/blocks/search.md-1-3 (1)
1-3: Fix generator to use consistent heading structure across all blocks in documentation files.The generator in
autogpt_platform/backend/scripts/generate_block_docs.pyuses h1 for the first block and h2 for subsequent blocks, while all subsections (What it is, How it works, Inputs, Outputs, Possible use case) use h3. This creates:
- MD001 violation: First block's h1 heading jumps directly to h3 subsections, skipping h2
- Structural inconsistency: Blocks in the same file use different heading levels (h1 vs h2), making the document hierarchy confusing
Solution: Update the generator to use consistent heading levels across all blocks. For example, use h2 for all block titles and h3 for all subsections (or h1/h2 if this is the top-level file). This affects all multi-block documentation files including search.md, github/.md, google/.md, twitter/*.md, and others.
docs/content/platform/blocks/exa/websets_polling.md-102-110 (1)
102-110: Fix malformed table structure at Exa Wait For Webset inputs.Line 105 has 6 cells instead of 4. The
target_statusrow mixes the parameter description with enum values in separate cells, breaking the table's expected column count. Consolidate the Type column to show the union of allowed values in a single cell (e.g.,"idle" | "completed" | "running").🔧 Proposed table fix
| Input | Description | Type | Required | |-------|-------------|------|----------| | webset_id | The ID or external ID of the Webset to monitor | str | Yes | -| target_status | Status to wait for (idle=all operations complete, completed=search done, running=actively processing) | "idle" | "completed" | "running" | No | +| target_status | Status to wait for (idle=all operations complete, completed=search done, running=actively processing) | "idle" \| "completed" \| "running" | No |docs/content/platform/blocks/airtable/schema.md-1-39 (1)
1-39: Standardize heading hierarchy and add blank lines around tables across all blocks.This multi-block documentation file has inconsistent heading structure. The first block uses h1 (# Airtable Create Field) followed directly by h3 subsections, violating MD001 (heading level progression). All subsequent blocks correctly use h2 followed by h3, creating inconsistency.
Additionally, every table is missing the required blank line before it (MD058)—section headers like
### Inputsand### Outputsare followed immediately by tables with no blank line separation.The first block's Inputs table also has a column count mismatch (line 18 has 5 pipe-separated values while the header has 4), violating MD056.
Recommended fixes:
- Change line 1 from
# Airtable Create Fieldto## Airtable Create Field- Add blank lines before all tables (after
### Inputs,### Outputs, and other section headers)- Fix the field_type row to have correct column alignment
Apply consistently across all five blocks (lines 1-39, 41-76, 78-111, 113-149, 151-187).
docs/content/platform/blocks/firecrawl/map.md-1-34 (1)
1-34: Fix heading hierarchy and Markdown formatting violations.The document uses h3 headings (###) for all subsections instead of h2 (##), which violates the MD001 rule that requires proper heading hierarchy after the h1 title. Additionally, tables are missing blank lines before them (MD058 violation).
The type notation
List[Dict[str, True]]for the "results" output (line 23) is also incorrect and should be corrected to use a proper string type representation.Consider reviewing the documentation generator to ensure:
- Use h2 (##) for all subsections (What it is, How it works, Inputs, Outputs, Possible use case)
- Add blank lines before and after tables
- Verify type annotations in output tables are accurate
🔧 Proposed structure fix
# Firecrawl Map Website - ### What it is + ## What it is Firecrawl maps a website to extract all the links. - ### How it works + ## How it works <!-- MANUAL: how_it_works --> This block uses Firecrawl's mapping API to discover all links on a website without extracting full content. It quickly scans the site structure and returns a comprehensive list of URLs found. The block is useful for understanding site architecture before performing targeted scraping or for building site maps. Results include both the raw list of links and structured results with titles and descriptions. <!-- END MANUAL --> - ### Inputs + ## Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| | url | The website url to map | str | Yes | - ### Outputs + ## Outputs + | Output | Description | Type | |--------|-------------|------| | error | Error message if the map failed | str | | links | List of URLs found on the website | List[str] | | results | List of search results with url, title, and description | List[Dict[str, str]] | - ### Possible use case + ## Possible use case <!-- MANUAL: use_case --> **Site Audit**: Map all pages on a website to identify broken links, orphan pages, or SEO issues. **Crawl Planning**: Discover site structure before deciding which pages to scrape in detail. **Content Discovery**: Find all blog posts, product pages, or documentation entries on a site. <!-- END MANUAL -->docs/content/platform/blocks/exa/websets_enrichment.md-1-37 (1)
1-37: Standardize heading hierarchy and fix table formatting across all blocks.This multi-block file has structural issues requiring consistent fixes:
- First block (Exa Cancel Enrichment) uses h1 followed by h3 subsections, skipping h2 (MD001 violation)
- Subsequent blocks correctly use h2 with h3 subsections
- All tables lack blank lines before them (MD058)
- Tables in "Exa Create Enrichment" and "Exa Update Enrichment" have column count mismatches where format enum values are incorrectly split across pipes (MD056)
For consistency:
- Change first block's title from h1 to h2
- Add blank lines before all tables
- Fix format columns to consolidate enum values (e.g.,
"text" | "date" | "number"should be a single cell)🔧 Proposed structure fix (for first block as example)
- # Exa Cancel Enrichment + ## Exa Cancel Enrichment ### What it is Cancel a running enrichment operation ### How it works <!-- MANUAL: how_it_works --> ... <!-- END MANUAL --> ### Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| ... ### Outputs + | Output | Description | Type | ...Apply this pattern consistently to all blocks in this file.
docs/content/platform/blocks/apollo/person.md-31-31 (1)
31-31: Update the output type for thecontactfield in the documentation.Line 31 shows
Dict[str, True], which is invalid syntax. The actual code definescontactas aContactobject—a structured Pydantic model with comprehensive contact details. Update the documentation to eitherContact(most accurate) orDict[str, Any]if a generic type is preferred.docs/content/platform/blocks/ayrshare/post_to_gmb.md-1-6 (1)
1-6: Fix markdown heading hierarchy and add blank lines around tables in generated block documentation.This file has markdown structure violations affecting 126 of 148 block documentation files: h1 title followed by h3 sections (skipping h2 per MD001), and tables without surrounding blank lines (MD058). The ayrshare and apollo blocks are part of a systematic issue where the
generate_block_docs.pyscript generates h3 headings instead of h2.Update the generator script to:
- Change section headings from h3 (
###) to h2 (##) for "What it is", "How it works", "Inputs", "Outputs", and "Possible use case" sections- Add blank lines before and after table blocks to comply with markdown spacing standards
This affects 126+ generated block documentation files and requires a single fix in the generator rather than manual updates to individual files.
docs/content/platform/blocks/exa/similar.md-1-6 (1)
1-6: Fix heading hierarchy and table spacing in the block documentation generator script.The markdown structure issues are confirmed across all generated block documentation:
- All 148 block doc files use h1 → h3 hierarchy (violating MD001), caused by line 318 in
generate_block_docs.pywhich assigns"#"to the first block heading instead of"##"- Tables lack blank lines before/after (MD058), because the generator appends tables directly after section headings without spacing logic
Fix the generator template at
autogpt_platform/backend/scripts/generate_block_docs.py:
- Line 318: Change
heading_level = "#" if is_first_in_file else "##"to always use"##", or adjust the initial content structure- Lines 327-334 (Inputs table) and 340-346 (Outputs table): Add blank lines before and after table rendering to comply with MD058
Regenerating docs with these fixes will correct all 148 block documentation files automatically.
docs/content/platform/blocks/github/reviews.md-13-23 (1)
13-23: Missing blank lines around tables violate Markdown formatting rules (MD058).Every input and output table is missing blank lines immediately before and after. Add a blank line before each table opening and after each table closing.
Example fix:
### Inputs | Input | Description | Type | Required | ...This should be applied systematically across all table definitions in the file.
Also applies to: 24-28, 30-37, 53-61, 63-69, 71-78, 94-99, 101-106, 108-115, 131-142, 144-151, 167-173, 175-179, 181-188
docs/content/platform/blocks/exa/websets_monitor.md-19-19 (1)
19-19: Table rows have too many cells (MD056).Lines 19, 23, and 188 contain more cells than the 4-column header. The header defines:
Input | Description | Type | Required. However:
- Line 19 has 5 cells (behavior_type, description, "search", "refresh", No)
- Line 23 has 5 cells (search_behavior, description, "append", "override", No)
- Line 188 has 6 cells (status, description, "enabled", "disabled", "paused", No)
The rows list multiple enum values as separate cells instead of combining them. Restructure these rows to fit the 4-column schema—for example, move enum options into the
Typecell using proper formatting (e.g.,"search" \| "refresh").docs/content/platform/blocks/github/reviews.md-28-28 (1)
28-28: Type annotationDict[str, True]is incorrect and appears throughout the platform blocks documentation.Line 28 specifies
comment_objectoutput type asDict[str, True], which is not a valid semantic type annotation. This same pattern appears in dozens of documentation files across the blocks platform (not just three files), suggesting a systematic documentation generator issue. The correct annotation should beDict[str, Any]to properly indicate "a dictionary with string keys and arbitrary values." This affects type clarity across the entire platform blocks documentation and should be corrected at the source (likely in the documentation generator).docs/content/platform/blocks/firecrawl/crawl.md-1-46 (1)
1-46: Fix Markdown linting violations (heading levels and table spacing).This file has the same structural issues as the other auto-generated block docs:
- Heading levels (MD001): Change h3 subsections to h2
- Table spacing (MD058): Add blank lines before and after tables
See the suggested fixes in the extract.md review for the exact formatting needed. These issues are systemic across all auto-generated block documentation files and should be addressed in the
generate_block_docs.pygenerator.Note: Line 10 has a minor style note (LanguageTool) suggesting "markdown" should be capitalized to "Markdown", but this is low priority compared to the structural issues.
docs/content/platform/blocks/firecrawl/extract.md-1-36 (1)
1-36: Fix Markdown linting violations in auto-generated output.This file has consistent structural issues likely originating from the generator:
Heading level progression (MD001): The document jumps from h1 (line 1) directly to h3 (lines 3, 6, 13, 21, 27). Subsection headings should be h2. Fix the generator to output
##instead of###for subsections.Missing blank lines around tables (MD058): Both the Inputs table (line 14) and Outputs table (line 22) require a blank line before and after them.
🔧 Suggested fixes for this file
# Firecrawl Extract -### What it is +## What it is Firecrawl crawls websites to extract comprehensive data while bypassing blockers. -### How it works +## How it works <!-- MANUAL: how_it_works --> This block uses Firecrawl's extraction API to pull structured data from web pages based on a prompt or schema. It crawls the specified URLs and uses AI to extract information matching your requirements. Define the data structure you want using a JSON schema for precise extraction, or use natural language prompts for flexible extraction. Wildcards in URLs allow extracting data from multiple pages matching a pattern. <!-- END MANUAL --> -### Inputs +## Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| | urls | The URLs to crawl - at least one is required. Wildcards are supported. (/*) | List[str] | Yes | | prompt | The prompt to use for the crawl | str | No | | output_schema | A Json Schema describing the output structure if more rigid structure is desired. | Dict[str, True] | No | | enable_web_search | When true, extraction can follow links outside the specified domain. | bool | No | + -### Outputs +## Outputs + | Output | Description | Type | |--------|-------------|------| | error | Error message if the extraction failed | str | | data | The result of the crawl | Dict[str, True] | + -### Possible use case +## Possible use case <!-- MANUAL: use_case --> **Product Data Extraction**: Extract structured product information (prices, specs, reviews) from e-commerce sites.Note: These same issues appear in the other auto-generated block documentation files. Consider fixing the
generate_block_docs.pyscript to emit proper Markdown heading levels and spacing rather than fixing each file individually.docs/content/platform/blocks/github/ci.md-1-43 (1)
1-43: Fix Markdown linting violations and table column mismatch.Same heading and table spacing issues as other block docs (see extract.md), plus an additional table structural issue:
Table column count mismatch (MD056, line 17): The "target" input row has 5 cells instead of 4. The type is split as
str | intacross two cells. Consolidate the union type into a single cell using a format likestr | intorstr/int.🔧 Suggested fix for the table column issue
| Input | Description | Type | Required | |-------|-------------|------|----------| | repo | GitHub repository | str | Yes | -| target | Commit SHA or PR number to get CI results for | str | int | Yes | +| target | Commit SHA or PR number to get CI results for | str \| int | Yes | | search_pattern | Optional regex pattern to search for in CI logs (e.g., error messages, file names) | str | No | | check_name_filter | Optional filter for specific check names (supports wildcards) | str | No |Additionally, apply the same heading level and table spacing fixes from extract.md (change h3 to h2, add blank lines before/after tables).
docs/content/platform/blocks/twitter/list_tweets_lookup.md-1-12 (1)
1-12: Fix heading hierarchy to match markdown standards.The file uses
### What it is(h3) immediately after the h1 title, violating the MD001 rule which requires heading levels to increment by only one level at a time. All subsection headings should use##(h2) instead of###(h3).🔧 Proposed fix
# Twitter Get List Tweets -### What it is +## What it is This block retrieves tweets from a specified Twitter list. -### How it works +## How it works <!-- MANUAL: how_it_works --> -### Inputs +## Inputs + -### Outputs +## Outputs + -### Possible use case +## Possible use case <!-- MANUAL: use_case -->Committable suggestion skipped: line range outside the PR's diff.
docs/content/platform/blocks/airtable/records.md-1-40 (1)
1-40: Fix heading inconsistency and add blank lines before tables.The file has two systematic issues:
Inconsistent heading levels for operations: The first operation "Airtable Create Records" (line 1) uses h1 (
#), while subsequent operations use h2 (##at lines 41, 77, 118, 164). All operations should use h2 for consistency.Missing blank lines before tables (MD058): All table headers (at lines 14, 24, 54, 61, 90, 99, 131, 146, 177, 185) immediately follow their section heading with no blank line, affecting markdown compliance and readability.
Update the generator to emit h2 for operation titles and add blank lines before all tables.
🔧 Proposed fixes (showing first two operations as example)
-# Airtable Create Records +## Airtable Create Records ### What it is Create records in an Airtable table ### How it works <!-- MANUAL: how_it_works --> ... ### Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------| ### Outputs + | Output | Description | Type | |--------|-------------|------| ### Possible use case <!-- MANUAL: use_case --> ... --- ## Airtable Delete Records ### What it is Delete records from an Airtable table ### How it works <!-- MANUAL: how_it_works --> ... ### Inputs + | Input | Description | Type | Required | |-------|-------------|------|----------|docs/content/platform/blocks/exa/code_context.md-1-40 (1)
1-40: Fix markdown structure: heading hierarchy and blank lines around tables.The file has two structural issues that originate in the
generate_block_docs.pygenerator:
Heading hierarchy violation (MD001): The file jumps from
# Exa Code Context(h1) directly to### What it is(h3). This is an intentional design pattern in the generator that applies to all block documentation files, but violates standard markdown hierarchy. Update the generator to use## What it is(h2) for subsections to maintain proper incremental hierarchy.Missing blank lines before tables (MD058): Lines 13 and 19 (Inputs and Outputs tables) need blank lines immediately before them for markdown compliance. The generator should append a blank line before appending table rows.
Both issues should be fixed in
generate_block_markdown()in the generator script rather than in individual files.🔧 Proposed fixes for generator output
# Exa Code Context -### What it is +## What it is Search billions of GitHub repos, docs, and Stack Overflow for relevant code examples -### How it works +## How it works <!-- MANUAL: how_it_works --> This block uses Exa's specialized code search API to find relevant code examples from GitHub repositories, official documentation, and Stack Overflow. The search is optimized for code context, returning formatted snippets with source references. The block returns code snippets along with metadata including the source URL, search time, and token counts. You can control response size with the tokens_num parameter to balance comprehensiveness with cost. <!-- END MANUAL --> -### Inputs +## Inputs + | Input | Description | Type | Required | -### Outputs +## Outputs + | Output | Description | Type | -### Possible use case +## Possible use case <!-- MANUAL: use_case -->docs/content/platform/blocks/exa/websets_import_export.md-13-35 (1)
13-35: Add blank lines around tables and fix table column count.Markdown linters expect blank lines before and after tables. Additionally, the input table has a structural issue on line 18: the
entity_typecolumn spans multiple pipes due to type union syntax ("company" | "person" | "article"), which causes the parser to count 6 cells instead of the expected 4. This will break table rendering.♻️ Proposed fixes
Add blank line before the table:
### Inputs + | Input | Description | Type | Required |Fix the entity_type row by escaping or restructuring the type union:
-| entity_type | Type of entities being imported | "company" | "person" | "article" | No | +| entity_type | Type of entities being imported (company, person, article) | str | No |Add blank line after the table:
| metadata | Metadata to attach to the import | Dict[str, True] | No | + ### Outputsdocs/content/platform/blocks/exa/search.md-13-31 (1)
13-31: Fix table structure: type unions in cells break column count and add blank lines.The Inputs table has two issues:
Malformed type union cells (lines 17–18): Type unions like
"keyword" | "neural" | "fast"and"company" | "research paper" | "news"span multiple pipes, causing the parser to count more columns than the header declares. These should be wrapped in backticks or escaped to be treated as single cell content.Missing blank lines: Add before and after the table.
♻️ Proposed fixes
Escape type unions with backticks:
| Input | Description | Type | Required | |-------|-------------|------|----------| | query | The search query | str | Yes | -| type | Type of search | "keyword" | "neural" | "fast" | No | -| category | Category to search within: company, research paper, news, pdf, github, tweet, personal site, linkedin profile, financial report | "company" | "research paper" | "news" | No | +| type | Type of search | `"keyword"` \| `"neural"` \| `"fast"` | No | +| category | Category to search within: company, research paper, news, pdf, github, tweet, personal site, linkedin profile, financial report | `"company"` \| `"research paper"` \| `"news"` | No |Add blank lines:
+ | Input | Description | Type | Required | ... | moderation | Enable content moderation to filter unsafe content from search results | bool | No | + ### Outputsdocs/content/platform/blocks/google/sheets.md-1-20 (1)
1-20: Fix Markdown heading levels and add blank lines around tables.Per markdown linting standards (MD001 and MD058):
- Line 1: Change
# Google Sheets Add Columnto## Google Sheets Add Column(h3 → h2 for top-level block headings)- Add blank line before line 13 (before first table)
- Add blank line after line 20 (after input table)
- Add blank line before line 22 (before output table)
- Add blank line after line 29 (after output table)
- Repeat this pattern for all remaining blocks
This affects all 34 blocks in the file and ensures consistent formatting.
docs/content/platform/blocks/exa/websets.md-1-11 (1)
1-11: Fix Markdown heading levels and add blank lines around tables.Per markdown linting rules (MD001 and MD058), the first heading should be h2, not h3, and all tables should be surrounded by blank lines. This affects consistency across the documentation.
Suggested fixes:
- Line 1: Change
# Exa Cancel Websetto## Exa Cancel Webset(repeat for all top-level block headings)- Add blank line before line 13 (before first table)
- Add blank line after line 16 (after input table)
- Add blank line before line 18 (before output table)
- Add blank line after line 25 (after output table)
- Repeat pattern for all remaining blocks
docs/content/platform/blocks/misc.md-3-3 (1)
3-3: Fix Markdown formatting: heading levels, table spacing, and hyphenation.Per markdown linting standards:
- Line 3: Change
### What it isto## Agent Executor(h3 → h2 for top-level block headings)- Line 14 and 19: Add blank lines before and after tables (MD058)
- Lines 50, 168: Change "Debian based" to "Debian-based" (hyphenation)
- Repeat heading and table formatting pattern for all remaining blocks
Also applies to: 14-14, 19-19, 50-50, 168-168
docs/content/platform/blocks/github/pull_requests.md-1-35 (1)
1-35: Address systematic markdown issues (see repo.md comments).This file has the same heading hierarchy, table formatting, and GitHub capitalization issues as the other auto-generated documentation files. Fix these in the
generate_block_docs.pytemplate.Additionally, note the table column count mismatches flagged at lines 59 and 210 (MD056), which suggest the table structure may not match the actual number of columns. Verify the table generation logic in the generator.
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | organization_num_employees_range | The number range of employees working for the company. This enables you to find companies based on headcount. You can add multiple ranges to expand your search results. | ||
|
|
||
| Each range you add needs to be a string, with the upper and lower numbers of the range separated only by a comma. | List[int] | No | | ||
| | organization_locations | The location of the company headquarters. You can search across cities, US states, and countries. | ||
|
|
||
| If a company has several office locations, results are still based on the headquarters location. For example, if you search chicago but a company's HQ location is in boston, any Boston-based companies will not appearch in your search results, even if they match other parameters. | ||
|
|
||
| To exclude companies based on location, use the organization_not_locations parameter. | ||
| | List[str] | No | | ||
| | organizations_not_locations | Exclude companies from search results based on the location of the company headquarters. You can use cities, US states, and countries as locations to exclude. | ||
|
|
||
| This parameter is useful for ensuring you do not prospect in an undesirable territory. For example, if you use ireland as a value, no Ireland-based companies will appear in your search results. | ||
| | List[str] | No | | ||
| | q_organization_keyword_tags | Filter search results based on keywords associated with companies. For example, you can enter mining as a value to return only companies that have an association with the mining industry. | List[str] | No | | ||
| | q_organization_name | Filter search results to include a specific company name. | ||
|
|
||
| If the value you enter for this parameter does not match with a company's name, the company will not appear in search results, even if it matches other parameters. Partial matches are accepted. For example, if you filter by the value marketing, a company called NY Marketing Unlimited would still be eligible as a search result, but NY Market Analysis would not be eligible. | str | No | | ||
| | organization_ids | The Apollo IDs for the companies you want to include in your search results. Each company in the Apollo database is assigned a unique ID. | ||
|
|
||
| To find IDs, identify the values for organization_id when you call this endpoint. | List[str] | No | | ||
| | max_results | The maximum number of results to return. If you don't specify this parameter, the default is 100. | int | No | | ||
|
|
There was a problem hiding this comment.
Fix table structure: multiline cell content breaks rendering and contains a spelling error.
The Inputs table has multiple issues:
-
Malformed table cells: Lines 16–24 contain cell content that spans multiple lines without proper markdown escaping (e.g.,
organization_num_employees_rangedescription,organization_locationsdescription with a line break before "If a company..."). In Markdown tables, multiline content requires<br>tags or must be escaped. -
Spelling error: Line 21 has "appearch" which should be "appear".
-
Missing blank lines: Add blank lines before and after the table.
♻️ Proposed fixes
Replace the Inputs table with properly escaped cells:
+
| Input | Description | Type | Required |
|-------|-------------|------|----------|
-| organization_num_employees_range | The number range of employees working for the company. This enables you to find companies based on headcount. You can add multiple ranges to expand your search results.
-
-Each range you add needs to be a string, with the upper and lower numbers of the range separated only by a comma. | List[int] | No |
-| organization_locations | The location of the company headquarters. You can search across cities, US states, and countries.
-
-If a company has several office locations, results are still based on the headquarters location. For example, if you search chicago but a company's HQ location is in boston, any Boston-based companies will not appearch in your search results, even if they match other parameters.
-
-To exclude companies based on location, use the organization_not_locations parameter.
- | List[str] | No |
+| organization_num_employees_range | The number range of employees working for the company. This enables you to find companies based on headcount. You can add multiple ranges to expand your search results.<br/>Each range you add needs to be a string, with the upper and lower numbers of the range separated only by a comma. | List[int] | No |
+| organization_locations | The location of the company headquarters. You can search across cities, US states, and countries.<br/>If a company has several office locations, results are still based on the headquarters location. For example, if you search chicago but a company's HQ location is in boston, any Boston-based companies will not appear in your search results, even if they match other parameters.<br/>To exclude companies based on location, use the organization_not_locations parameter. | List[str] | No |
| organizations_not_locations | Exclude companies from search results based on the location of the company headquarters. You can use cities, US states, and countries as locations to exclude.
-
-This parameter is useful for ensuring you do not prospect in an undesirable territory. For example, if you use ireland as a value, no Ireland-based companies will appear in your search results.
- | List[str] | No |
+<br/>This parameter is useful for ensuring you do not prospect in an undesirable territory. For example, if you use ireland as a value, no Ireland-based companies will appear in your search results. | List[str] | No |Add blank line after the table:
| max_results | The maximum number of results to return. If you don't specify this parameter, the default is 100. | int | No |
+
### Outputs🧰 Tools
🪛 LanguageTool
[grammar] ~21-~21: Ensure spelling is correct
Context: ...on, any Boston-based companies will not appearch in your search results, even if they ma...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
14-14: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
16-16: Table pipe style
Expected: leading_and_trailing; Actual: leading_only; Missing trailing pipe
(MD055, table-pipe-style)
16-16: Table column count
Expected: 4; Actual: 2; Too few cells, row will be missing data
(MD056, table-column-count)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/apollo/organization.md around lines 14 - 37,
The Inputs table's cells contain unescaped multiline content and a typo causing
rendering issues; fix by converting multiline descriptions into single-line
cells (use <br> tags or join lines) for organization_num_employees_range,
organization_locations (merge the broken sentence so "appear" replaces
"appearch"), organizations_not_locations, and any other wrapped descriptions,
ensure the header/table has a blank line before and after it, and verify column
alignment for List[int]/List[str]/str/int types so the markdown table renders
correctly.
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | repo_url | URL of the GitHub repository | str | Yes | | ||
| | sha | The SHA of the commit to set status for | str | Yes | | ||
| | state | The state of the status (error, failure, pending, success) | "error" | "failure" | "pending" | Yes | | ||
| | target_url | URL with additional details about this status | str | No | | ||
| | description | Short description of the status | str | No | | ||
| | check_name | Label to differentiate this status from others | str | No | |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n docs/content/platform/blocks/github/statuses.md | head -30Repository: Significant-Gravitas/AutoGPT
Length of output: 1650
🏁 Script executed:
# Search for similar pattern: state parameter with split union types across cells
find docs/content/platform/blocks -name "*.md" -exec grep -l "| state |" {} \; | head -5Repository: Significant-Gravitas/AutoGPT
Length of output: 316
🏁 Script executed:
# Count how many markdown files in blocks directory
find docs/content/platform/blocks -name "*.md" | wc -lRepository: Significant-Gravitas/AutoGPT
Length of output: 75
🏁 Script executed:
# Search for malformed table rows with union types split across cells (pattern: multiple pipe-quoted strings)
rg '\| "[a-z_]+" \| "[a-z_]+"' docs/content/platform/blocks --type md | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 1375
Table column count mismatch in Inputs table — systemic generator defect.
Line 18: The state parameter's type is split across multiple table cells ("error" | "failure" | "pending"), creating 5-6 columns instead of the expected 4 (Input, Description, Type, Required). This breaks markdown table structure and renders incorrectly.
This is a systemic defect in the document generator: at least 10+ other blocks exhibit the same issue (e.g., sort_by, language, output_format, sampling_method). Union types in the Type column are being split across separate cells instead of escaped as a single cell value.
🔧 Expected table format
The Type column should contain the complete union type as a single cell:
- | state | The state of the status (error, failure, pending, success) | "error" | "failure" | "pending" | Yes |
+ | state | The state of the status | "error" \| "failure" \| "pending" \| "success" | Yes |(Note: Pipe characters in markdown cells should be escaped)
The generator must handle union type formatting consistently across all blocks before release.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | repo_url | URL of the GitHub repository | str | Yes | | |
| | sha | The SHA of the commit to set status for | str | Yes | | |
| | state | The state of the status (error, failure, pending, success) | "error" | "failure" | "pending" | Yes | | |
| | target_url | URL with additional details about this status | str | No | | |
| | description | Short description of the status | str | No | | |
| | check_name | Label to differentiate this status from others | str | No | | |
| | Input | Description | Type | Required | | |
| |-------|-------------|------|----------| | |
| | repo_url | URL of the GitHub repository | str | Yes | | |
| | sha | The SHA of the commit to set status for | str | Yes | | |
| | state | The state of the status | "error" \| "failure" \| "pending" \| "success" | Yes | | |
| | target_url | URL with additional details about this status | str | No | | |
| | description | Short description of the status | str | No | | |
| | check_name | Label to differentiate this status from others | str | No | |
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/github/statuses.md around lines 14 - 21, The
Inputs table is rendered with union types split into multiple markdown cells
(see the `state` row and other fields like `sort_by`, `language`,
`output_format`, `sampling_method`), breaking the 4-column layout; update the
doc generator to treat union type values as a single table cell by escaping pipe
characters or wrapping the entire union in an inline code span/HTML entity when
generating the Type column so `"error" | "failure" | "pending"` stays one cell
and the table remains 4 columns (Input, Description, Type, Required).
| | author_id | The Medium AuthorID of the user. You can get this by calling the /me endpoint of the Medium API. | ||
|
|
||
| curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://api.medium.com/v1/me" the response will contain the authorId field. | str | No | |
There was a problem hiding this comment.
Line 241 contains a curl command example that exposes an authorization token pattern:
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" https://api.medium.com/v1/me"
Even though YOUR_ACCESS_TOKEN is a placeholder, this pattern violates security best practices by showing how credentials are passed in plaintext. Gitleaks correctly flagged this as a high-severity security issue.
Recommended fix:
- Replace the direct curl example with a reference to environment variables or secure credential management
- Add a warning: "Never include actual tokens in examples or code"
- Point users to the Medium API documentation for secure authentication
Would you like me to suggest a secure refactoring of this documentation section?
🧰 Tools
🪛 Gitleaks (8.30.0)
[high] 241-241: Discovered a potential authorization token provided in a curl command header, which could compromise the curl accessed resource.
(curl-auth-header)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/misc.md around lines 239 - 241, Replace the
inline curl example that includes the "Authorization: Bearer YOUR_ACCESS_TOKEN"
pattern with a secure example that references an environment variable (e.g.,
$MEDIUM_ACCESS_TOKEN) or secret manager usage instead of a literal token, remove
the trailing stray quote in the example, add a short warning line "Never include
actual tokens in examples or code", and append a pointer to the Medium API
authentication docs for secure token handling; update the table cell text for
author_id to reference obtaining the authorId via the /me endpoint without
showing plaintext tokens.
| ### Inputs | ||
| | Input | Description | Type | Required | | ||
| |-------|-------------|------|----------| | ||
| | query | Search query to find agents | str | No | | ||
| | category | Filter by category | str | No | | ||
| | sort_by | How to sort the results | "rating" | "runs" | "name" | No | | ||
| | limit | Maximum number of results to return | int | No | | ||
|
|
There was a problem hiding this comment.
Fix table corruption caused by pipe characters in the sort_by value.
Line 60 has unescaped pipe characters in the sort_by field which break the markdown table structure. The row currently has 6 cells instead of 4:
| sort_by | How to sort the results | "rating" | "runs" | "name" | No |
This should be rendered as a union type or quoted string in a single cell:
🔧 Proposed fix
- | sort_by | How to sort the results | "rating" | "runs" | "name" | No |
+ | sort_by | How to sort the results | "rating", "runs", or "name" | No |Or, if type syntax prefers pipes:
- | sort_by | How to sort the results | "rating" | "runs" | "name" | No |
+ | sort_by | How to sort the results | "rating" \| "runs" \| "name" | No |🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
56-56: Tables should be surrounded by blank lines
(MD058, blanks-around-tables)
60-60: Table column count
Expected: 4; Actual: 6; Too many cells, extra data will be missing
(MD056, table-column-count)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/system/store_operations.md around lines 55 -
62, The table row for the sort_by input contains unescaped pipe characters which
split the cell into extra columns; update the sort_by row so the type is a
single cell by quoting or code-formatting the union (e.g., "rating | runs |
name" or `rating | runs | name`) or replacing pipes with HTML entity | so
the row becomes four cells: header, description, type, required; edit the line
containing sort_by to use one of these forms to restore proper markdown table
structure.
| # Twitter Bookmark Tweet | ||
|
|
||
| ### What it is |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n docs/content/platform/blocks/twitter/bookmark.md | head -50Repository: Significant-Gravitas/AutoGPT
Length of output: 2535
🏁 Script executed:
# Check if generator script exists
find . -name "generate_block_docs.py" -o -name "*generate*" -type f | grep -E "\.(py|js|ts)$" | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 479
🏁 Script executed:
# Look for other twitter block files to compare structure
find docs/content/platform/blocks/twitter -type f -name "*.md" | head -10Repository: Significant-Gravitas/AutoGPT
Length of output: 570
🏁 Script executed:
cat -n ./autogpt_platform/backend/scripts/generate_block_docs.py | head -100Repository: Significant-Gravitas/AutoGPT
Length of output: 3263
🏁 Script executed:
# Check another twitter block file to see if same pattern exists
cat -n docs/content/platform/blocks/twitter/like.md | head -40Repository: Significant-Gravitas/AutoGPT
Length of output: 3010
🏁 Script executed:
# Search the generator script for heading generation logic
grep -n "###\|##\|^#" ./autogpt_platform/backend/scripts/generate_block_docs.py | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 938
🏁 Script executed:
# Look for where markdown heading output is generated in the generator
rg -A 3 -B 3 "# \{1,\}|markdown|heading" ./autogpt_platform/backend/scripts/generate_block_docs.py | head -80Repository: Significant-Gravitas/AutoGPT
Length of output: 2009
🏁 Script executed:
# Search for the template or function that generates block documentation
grep -n "def.*markdown\|def.*generate\|def.*doc" ./autogpt_platform/backend/scripts/generate_block_docs.py | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 425
🏁 Script executed:
# Let's see the full generate_block_markdown function to understand the complete structure
sed -n '347,410p' ./autogpt_platform/backend/scripts/generate_block_docs.pyRepository: Significant-Gravitas/AutoGPT
Length of output: 2402
🏁 Script executed:
# Check if there are any other block documentation files to see if this pattern is consistent
rg "^# " docs/content/platform/blocks --type md | head -20Repository: Significant-Gravitas/AutoGPT
Length of output: 1486
Fix generator heading hierarchy: section headers should adjust based on parent block level.
The generator script at ./autogpt_platform/backend/scripts/generate_block_docs.py hardcodes section headers (lines 362, 367, 379, 393, 403) as h3 (###), but uses h1 (#) for the first block in a file. This creates MD001 violations—jumping from h1 directly to h3 without h2. Section headers should be one level below their parent block heading:
- For h1 blocks: use h2 (
##) for sections - For h2 blocks: use h3 (
###) for sections
Update the generate_block_markdown() function to derive section_heading_level from heading_level instead of hardcoding h3 throughout.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
3-3: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
In @docs/content/platform/blocks/twitter/bookmark.md around lines 1 - 3, The
section headers in generate_block_markdown() are hardcoded as h3 (###); change
the function to compute section_heading_level = heading_level + 1 and use that
computed level when emitting all section headings (e.g., "What it is", "Inputs",
"Outputs", "Examples", etc.) instead of the literal "###"; update every place in
generate_block_markdown() that currently injects "###" to use the derived
section_heading_level so h1 blocks produce "##" sections and h2 blocks produce
"###" sections.
Accept dev's docs restructure (docs/content/platform → docs/platform). Resolves merge conflicts by accepting dev's file deletions. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Update DEFAULT_OUTPUT_DIR from docs/content/platform/blocks to docs/platform/blocks to match the new docs structure. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add block documentation files that were generated with improved descriptions from Bobby's GitBook site. These docs include technical explanations and use cases for blocks including Twitter, Google, GitHub, Wolfram, ZeroBounce, and many other integrations. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
|
Conflicts have been resolved! 🎉 A maintainer will review the pull request shortly. |
github-actions
bot
removed
the
conflicts
| # Default output directory relative to repo root | ||
| DEFAULT_OUTPUT_DIR = ( | ||
| Path(__file__).parent.parent.parent.parent / "docs" / "platform" / "blocks" | ||
| ) |
There was a problem hiding this comment.
Path mismatch between generate script and CI/migrate paths
High Severity
The DEFAULT_OUTPUT_DIR in generate_block_docs.py uses docs/platform/blocks while migrate_block_docs.py (lines 101 and 153-159) and all CI workflows use docs/content/platform/blocks. The actual documentation files in this PR are at docs/platform/blocks/. This mismatch causes the CI workflow to never trigger on doc changes, the git diff to check the wrong directory, and the migration script to read from/write to a non-existent location.
Additional Locations (2)
| desc = inp.description or "-" | ||
| # Escape pipes in description | ||
| desc = desc.replace("|", "\\|") | ||
| lines.append(f"| {inp.name} | {desc} | {inp.type_str} | {required} |") |
There was a problem hiding this comment.
Newlines in descriptions break markdown table formatting
Medium Severity
The table generation code escapes pipe characters in descriptions but does not handle newlines. When a field description contains newlines (which many do, as seen in the generated Apollo docs), the markdown table row breaks across multiple lines, producing invalid markdown that won't render correctly. The generated files like docs/platform/blocks/apollo/people.md show table rows spanning lines 16-21 instead of being on a single line. Newlines need to be replaced with spaces or <br> tags to maintain valid table syntax.
🤖 Generated with Claude Code
Co-Authored-By: Claude Opus 4.5 noreply@anthropic.com
Changes 🏗️
Checklist 📋
For code changes:
Example test plan
For configuration changes:
.env.defaultis updated or already compatible with my changesdocker-compose.ymlis updated or already compatible with my changesExamples of configuration changes
Note
Establishes a robust, automated documentation pipeline for blocks and refreshes block descriptions for clearer docs.
scripts/generate_block_docs.py(auto-generates docs from block schemas, preserves MANUAL sections) andscripts/migrate_block_docs.py(migrates legacy manual content)docs-block-sync.ymlfails PRs when docs drift; shows diff and remediation stepsdocs-claude-review.yml(accuracy/quality checks) anddocs-enhance.yml(LLM-assisted manual sections, optional PR creation)test_generate_block_docs.py)docs/platform/blocks/**(e.g., Airtable, Apollo, Ayrshare, Bannerbear) with standardized sectionsWritten by Cursor Bugbot for commit 04cf8d0. This will update automatically on new commits. Configure here.
Summary by CodeRabbit
Documentation
Chores
✏️ Tip: You can customize this high-level summary in your review settings.