Skip to content

docs: add Apify glossary page linked from the footer - #2976

Draft
marcel-rbro wants to merge 6 commits into
masterfrom
docs/glossary
Draft

marcel-rbro wants to merge 6 commits into
masterfrom
docs/glossary

Conversation

@marcel-rbro

Copy link
Copy Markdown
Contributor

Adds a single A–Z glossary of Apify-specific terms at /glossary.

Not in the page tree

The sidebars in sources/platform/sidebars.js are autogenerated per directory (get-started, actors, storage, proxy, integrations, account, security). This page sits at the root of sources/platform/, outside all of them, so no sidebar picks it up and it adds nothing to the navigation tree. Verified in the build output: the page renders with no sidebar container, and /glossary appears in no sidebar menu on any page.

It is reached from the Reference column in the footer instead, added in apify-docs-theme/src/config.js. Happy to move it to the "For AI" column if that reads better — see the open questions below.

Scope

Apify-specific concepts plus the proxy family. Terms common to web scraping and software development in general (web scraping, crawling, session, JSON, headless browser) are deliberately left out — they add no Apify-specific value and every entry we keep is one more thing to maintain.

Each entry is one sentence that links to the page owning the concept, so the glossary routes rather than duplicates. The linked page stays canonical, which keeps drift low.

32 terms, one ## heading each, so every term gets a stable anchor (/glossary#dataset) that other pages can link to. toc_max_heading_level: 2 keeps the table of contents to the term list.

Agent readability

The page is picked up automatically by the llms-txt plugin — no separate pipeline. Confirmed in the build output:

  • listed in llms.txt under a ## Glossary category (added a routeRules entry in docusaurus.config.js, otherwise it fell through as lowercase glossary)
  • full content in llms-full.txt
  • .md counterpart served at /glossary.md
  • present in sitemap_base.xml

Verification

  • docusaurus build passes, exit 0, zero broken links (onBrokenLinks is throw)
  • Every internal link checked against the slug: front matter on master
  • vale --minAlertLevel=error: 0 errors
  • markdownlint: clean

Open questions

  1. Footer column — Reference (current) or "For AI", next to llms.txt?
  2. Do the three newer terms belong in v1 — Apify AGI, x402, and webhook? They're all documented, but they're the least settled entries here.
  3. Top-level redirect — the URL is already /glossary, so no redirect is needed. Flagging only in case there's a reason to also keep a path under /get-started.
  4. Naming — entries follow standards/terminology.md casing, so concept terms are lowercase (build, dataset, schedule) while product names are capitalized. That makes the A–Z list mixed-case. Worth a look.

A previous Academy glossary was removed in #2130 on SEO grounds (low traffic, generic web-scraping terms). This one is deliberately different: Apify-specific vocabulary only, agent-first, and kept out of the navigation, so it isn't competing for the same traffic.

Draft — opening for direction on the four questions above before polishing the wording.

Adds a single A-Z glossary of Apify-specific terms at /glossary.

The page sits at the root of sources/platform/, outside every directory
the sidebars autogenerate from, so it stays out of the page tree. It is
reached from the Reference column in the footer instead.

Scope is Apify-specific concepts plus the proxy family. Terms common to
web scraping and software development in general are excluded. Each entry
is one sentence that links to the page owning the concept, so the glossary
routes rather than duplicates.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GmXAuRf1CPE7WyGTr3QR1T
@apify-service-account

apify-service-account commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

✅ Preview for this PR (commit 8fec708) is ready at https://pr-2976.preview.docs.apify.com (see action run).

marcel-rbro and others added 5 commits September 14, 2026 18:05
Adds Output, output schema, MCP connectors, and MCP Proxy, taking the
glossary to 36 terms.

Output comes from the Sales Glossary, which defines it as its own
concept; the page already defined input schema but neither output nor
its schema. MCP connectors and MCP Proxy are both named as Apify terms
in standards/terminology.md, which gives each its own casing rule, and
MCP connectors has its own page.

MCP Proxy has no page of its own - it is documented inline on the MCP
connectors page, which is what its entry links to.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GmXAuRf1CPE7WyGTr3QR1T
The monetization index lists only two current pricing models, pay per
event and pay per usage. Rental survives as a page carrying a sunset
caution: new rental Actors stopped on April 1, 2026, and the remaining
ones migrate to pay-per-usage on October 1, 2026.

The entry presented rental as a live model alongside the other two.
It now states the retirement and the migration target.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GmXAuRf1CPE7WyGTr3QR1T
Each entry now carries a second sentence describing what the term does
in practice, and cross-links the concepts it touches, so a reader can
move between related terms without going back to the sidebar.

Definitions are drawn from each target page so the glossary stays
consistent with the page that owns the concept.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GmXAuRf1CPE7WyGTr3QR1T
Pay per event + usage is an option on the pay-per-event model rather
than a pricing model of its own, but it changes what users are charged
and it has consequences worth surfacing: it lowers the Actor's quality
score and makes the Actor ineligible for agentic payments.

Entered under its Console label so a reader who meets the toggle can
look it up, and framed as an option so it does not read as a third
pricing model.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GmXAuRf1CPE7WyGTr3QR1T
It is an option on the pay-per-event model rather than a term of its
own, so a separate A-Z entry overstated it. The PPE entry now names the
option and its two consequences: a lower quality score and ineligibility
for agentic payments.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GmXAuRf1CPE7WyGTr3QR1T
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants