Slab's many-to-many topic model doesn't map cleanly to Guru's one-collection-per-card hierarchy. Use the API approach for anything beyond 50 posts — manual export loses metadata and structure.
There is no native one-click migration path from Slab to Guru. While Guru offers a "Slab" import option in its content migration settings, it functions by ingesting a manually exported Markdown ZIP file from Slab's admin panel — not a direct API-to-API transfer. The fundamental architectural mismatch is significant: Slab organizes content in a many-to-many Topics + Posts model using Quill Delta format internally, while Guru enforces a strict hierarchical Collections → Folders → Cards structure using HTML. Migrating at any meaningful scale requires a custom API-driven pipeline to handle content format conversion (Quill Delta to HTML), topic-to-collection mapping, internal link rewriting, attachment re-hosting, and verification metadata preservation.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
Public Cards sunset
Guru's December 2025 release notes indicate that new Public Cards can no longer be created. If your Slab instance includes publicly accessible content, test fit first — Guru may not support your public knowledge sharing needs going forward.
Verification defaults changed
Guru's documentation indicates that Collections created after January 2026 default cards to "Does not expire." Do not rely on defaults if you want periodic re-verification — set verification intervals explicitly via the API during migration.
Slab API access requires Business or Enterprise plan
Slab offers a GraphQL API, but it's only available on Business or Enterprise plans. If you're on the free or Startup plan, your only extraction option is the manual Markdown export.
Build with backpressure in mind
Since Guru doesn't publish specific rate limits, start conservatively (1–2 requests/second) and increase until you see 429s. Implement exponential backoff with jitter. Log every 429 response with timestamp and endpoint so you can calculate the effective limit for your account tier.
This is a structural outline with checkpoint persistence and retry logic, not production-ready code
A real implementation additionally needs: image download/re-upload with URL replacement in HTML, tag creation and assignment, folder creation before card creation, and a comprehensive validation pass comparing source and destination record counts.
The runbook
Work top to bottom. Tick steps as you go — your progress is saved in this browser.
01 Discovery Decide what content deserves to move before you plan how to move it.
Objective A content inventory with a keep/rewrite/retire decision on every article and an agreed URL strategy.
Keep these open
-
Inventory all content in Slab
Count articles, categories, attachments, images and embedded media, and pull page views and last-updated dates for each article. Usage data is what makes the next decision defensible rather than political.
Data Profiler Get real record counts instead of estimating from memory -
Make a keep, rewrite or retire call on every article
Most knowledge bases are half stale. Migrating everything imports the staleness and doubles the work; use views and last-updated to triage, and get the owning team to confirm. This usually removes 30-50% of scope.
Migrating stale content is the most common knowledge-base migration mistake — it costs effort and actively degrades the new site.
-
Agree the URL and redirect strategy
Decide the Guru URL structure and whether you can serve 301 redirects from the old paths. Public help centres carry real search traffic and inbound links; losing it is a measurable commercial impact.
Without 301 redirects from old article URLs you lose accumulated search ranking and every external link and bookmark breaks.
-
Map the information architecture
Document the current category tree and design the target one, checking whether Guru supports your nesting depth. Deeply nested hierarchies frequently have to be flattened, which changes navigation for everyone.
-
Confirm permissions, audiences and localisation scope
Establish which content is public, internal or restricted, and how Guru models that. Then confirm how many locales you have and whether translation relationships between articles survive the move.
Slab → Guru specifics
- Small team, <50 posts, no dev resources
- Manual Markdown export → Guru import. Accept the hierarchy loss and fix manually.
- Mid-size team, 50–500 posts, some dev bandwidth
- API-based migration with a focused script. Budget 1–2 weeks of engineering time.
- Enterprise, 500+ posts, tight deadline
- Managed migration service or dedicated ETL pipeline. The cost of engineering time and risk of data loss often exceeds the service fee.
- Ongoing sync (Slab and Guru running in parallel)
- Zapier/Make for incremental new content, paired with a one-time bulk migration for historical data.
Don't move on until
- Full content inventory with page views and last-updated dates
- Keep / rewrite / retire decision recorded per article
- URL and redirect strategy agreed with whoever owns SEO
02 Data Audit Audit the markup, the links and the assets — that is where KB migrations break.
Objective A content export with markup, internal links and every embedded asset accounted for.
Keep these open
-
Export content and assess markup fidelity
Export articles in the richest format available and inspect what survived: tables, code blocks, callouts, nested lists, anchors and embedded video. Rich formatting is where fidelity is lost, and it is lost quietly.
HTML-to-Markdown conversion routinely mangles nested lists, tables and code blocks. Inspect the output rather than trusting the converter.
Data Profiler Profile the Slab export for nulls, outliers and type drift -
Inventory every internal link and cross-reference
Extract all internal links, anchor links and article cross-references. These break by default: the target URL structure differs, so every internal link needs rewriting as part of the load, not afterwards.
Internal links left pointing at old URLs turn the new knowledge base into a maze of 404s on day one.
-
Inventory images, attachments and embedded media
List every asset with its URL, size and type, and confirm each still resolves. Assets hosted on the old platform's CDN will 404 the moment you decommission it, so they must be rehosted, not referenced.
Images referenced from the source platform's CDN break when the old account closes. Download and rehost every asset.
-
Find and fix broken links and orphans
Crawl for existing broken internal and external links, and find articles no category links to. Fix them before migrating — a migration is a bad time to discover pre-existing rot.
-
Check for PII and internal information in public content
Scan for customer names, internal hostnames, credentials in code samples and screenshots containing real data. Republishing these on a public help centre is a disclosure, and screenshots are the usual culprit.
PII & Compliance Scanner Find regulated fields before they land in a new system -
Normalise metadata
Standardise authors, tags, timestamps to UTC, and locale codes. Author mapping needs a decision for people who have left — attribution to a deleted user usually fails the import.
Slab → Guru specifics
- Published posts
- Count by topic. Identify orphaned posts (no topic assigned).
- Draft posts
- Decide whether to migrate drafts or archive them. Slab's export only includes published content.
- Secret topics
- The secret topic trap: An admin can only export content they have permission to view. Ensure the migration account has access to all secret topics.
- Topic hierarchy and depth
- Identify any nesting deeper than three levels. Guru folders cap at three nested levels, so deeper Slab trees need flattening.
- Multi-topic posts
- Flag every post that belongs to multiple topics. These require a primary topic decision.
Don't move on until
- Content exported with markup fidelity assessed
- Every internal link and asset reference inventoried
- Broken links and missing assets fixed or logged
03 Field Mapping Map structure, metadata, permissions and — above all — URLs.
Objective A mapping covering article fields, taxonomy, permissions and a complete old-to-new URL map.
Keep these open
-
Map the article schema
Map title, body, excerpt, author, dates, status, tags, SEO metadata and any custom properties. Confirm which fields Guru lets you set on import versus which it computes — computed dates are a common surprise.
Schema Mapper Opens pre-loaded with the Slab → Guru field pair -
Map the taxonomy and hierarchy
Map categories, sections and tags to the target structure, resolving any nesting-depth limit explicitly. If you must flatten, decide how the lost level is preserved — usually as a tag or a title prefix.
JSON to CSV Converter Flatten nested API responses into a reviewable sheet -
Map permissions and audience segmentation
Map public, logged-in, and role-restricted visibility to Guru's model. Verify the mapping deliberately: internal content accidentally published publicly is the highest-severity failure in this whole category.
Permission mapping errors publish internal documentation to the open web. Verify visibility on every restricted article after load.
-
Build the complete old-to-new URL map
Produce a row per article mapping the old URL to the new one, then confirm exactly where the 301s will be served — Guru, a CDN, or your own web layer. Without this artifact the redirect step cannot be executed at all.
-
Define the markup conversion and link-rewrite rules
Specify how each markup construct converts and how internal links are rewritten using the URL map. Write it as a repeatable transform, not manual edits — you will run it more than once.
Data Format Converter Reshape the export into the format Guru's importer expects -
Plan localisation and freeze the spec
Confirm how translated articles link to their source language in Guru, then version and sign off the mapping spec.
Don't move on until
- Article schema and taxonomy mapped
- Permission and audience model mapped to target equivalents
- Complete URL map produced and redirect method confirmed
04 Test Migration Pilot the hardest articles, then read them.
Objective A pilot load whose formatting, links, assets and search all hold up under human review.
Keep these open
-
Configure Guru with the agreed structure
Create the category tree, permission groups, locales and branding before loading. Articles loaded before their categories exist land uncategorised and have to be moved by hand.
-
Pick the most difficult articles as the pilot
Choose 20-50 articles for difficulty: the longest, the most heavily formatted, ones with tables and code blocks, deep internal linking, many images, embedded video, restricted visibility, and non-Latin scripts. Easy articles prove nothing.
-
Run the conversion and load with link rewriting
Apply the markup conversion, rewrite internal links from the URL map, upload and re-reference assets, then load. Log every conversion warning rather than suppressing it.
-
Read every pilot article side by side
Open source and target together and compare rendering. This step is manual on purpose: no automated check catches a table that collapsed into a paragraph or a code block that lost its indentation.
-
Click every link and load every asset
Verify each internal link resolves, each image loads from the new host, each attachment downloads and each embed plays. Assets still served from the old CDN are the defect that surfaces only after decommissioning.
Migration Validation Tool Diff the pilot batch against source before scaling up -
Test search and permissions
Search for known terms and confirm the right articles rank, then verify every restricted pilot article is invisible to an anonymous browser. Test permissions from a logged-out session, not an admin one.
Don't move on until
- Complex articles render correctly with formatting intact
- Every internal link and asset in the pilot resolves
- Search returns sensible results for the pilot content
05 Cutover Publish, redirect, and keep the search traffic.
Objective All in-scope content live in Guru with redirects serving and search engines informed.
Keep these open
-
Load the full content set ahead of the switch
Run the full conversion and load into Guru, unpublished or on a staging domain. Content migration differs from data migration here: you can stage the whole thing before anyone sees it.
-
Publish the runbook with the redirect step first-class
Sequence the freeze, final delta, publish, redirect activation, sitemap submission and link updates, with owners for each. Redirect activation is the step with lasting commercial consequences, so it gets explicit ownership.
-
Freeze editing and migrate the delta
Stop editing in Slab, then convert and load anything changed since the full load. Announce the freeze to every team that publishes — content teams are used to editing whenever they like.
-
Publish and verify permissions live
Publish the content set, then immediately verify restricted articles are not publicly reachable using an anonymous session. Do this before announcing the new site, not after.
Verify restricted content from a logged-out browser. An admin session will show you everything and tell you nothing.
Migration Validation Tool Confirm the final delta landed before you reopen -
Activate 301 redirects and submit the sitemap
Turn on the redirects from the URL map, then spot-check a sample of high-traffic old URLs and confirm each returns 301 to the right article. Submit the new sitemap and keep the old one reachable until search engines have recrawled.
Redirect chains and redirect loops both leak ranking. Verify each redirect resolves in a single hop.
-
Repoint in-product and support links
Update help links embedded in your product, in support macros, in email templates and in onboarding material. These are the links your existing customers actually use, and they are easy to forget.
Don't move on until
- All content loaded, categorised and correctly permissioned
- 301 redirects live and verified from a sample of old URLs
- Sitemap submitted and support links repointed
06 Validation Watch traffic, links and search rankings for weeks, not hours.
Objective Verified content completeness, healthy redirects, and search traffic recovered to baseline.
Keep these open
-
Reconcile content counts and assets
Compare article counts by category and status, plus asset counts, against source. Confirm every article in the keep list is present and every retired one genuinely is not.
Migration Validation Tool Reconcile Slab and Guru record-for-record -
Crawl the new site for broken links and assets
Run a full crawl for 404s, broken images and missing attachments, and fix everything it finds. Repeat the crawl after the fixes rather than assuming they worked.
-
Verify the redirects at scale
Test every mapped old URL for a single-hop 301 to the right destination. Chains and loops both leak ranking and are invisible unless you check the whole map, not a sample.
-
Monitor organic traffic and rankings for four to eight weeks
Track organic sessions, impressions and rankings for your top articles against baseline. A dip in the first two weeks is normal; one that has not recovered by week six is a redirect or indexing problem to investigate.
Do not decommission the old platform until search traffic has recovered — you may still need the old URLs to diagnose a ranking loss.
-
Verify search, permissions and feedback loops
Confirm on-site search returns good results for real queries, re-verify restricted content from a logged-out session, and check article feedback and analytics are collecting.
-
Sign off and decommission on a delay
Get acceptance against the Discovery criteria, keep Slab available read-only until traffic has recovered, take a final export, and only then close the account.
Slab → Guru specifics
- Verification metadata
- Which posts have active verification owners and intervals? You'll want to re-establish these in Guru.
Don't move on until
- Article counts reconciled and no broken links remain
- Redirects returning 301 with no chains or loops
- Organic traffic recovered to within tolerance of baseline
Field mapping reference
The field-by-field mapping for each object. Use this as the starting point for your mapping spec.
Object Equivalent
| Slab field | Guru field | Notes |
|---|---|---|
| Post | Card | 1:1 mapping. Content format changes from Quill Delta/Markdown to HTML. |
| Topic (top-level) | Collection | Each major Slab topic becomes a Guru Collection. |
| Topic (nested/child) | Folder | Sub-topics map to Folders within a Collection. Max 3 levels. |
| Topic (as label) | Tag | When a post has multiple topics, secondary topics become Guru Tags. |
| Post verification | Card verification | Map verification owner → Guru verifier; set verification interval. |
| Post comments | Card comments | Guru supports comments on Cards; migrate via API if needed. |
| Post author | Card owner / metadata | Map via email address to preserve authorship. |
| Secret topic | Collection with restricted group | Guru's group-based permissions replace Slab's secret topic model (see permission mapping below). |
| Embedded integration | Inline URL or unsupported | GitHub/Figma/Loom embeds have no Guru equivalent. |
Quill Delta Operation HTML Reference
| Slab field | Guru field | Notes |
|---|---|---|
| insert: "text" | bold: true | |
| insert: "text" | italic: true | |
| insert: "text" | link: "url" | Check for internal Slab links here |
| insert: "text" | code: true | Inline code |
| insert: "text" | strike: true | |
| insert: "\n" | header: 1 | Delta signals headers on the trailing newline |
| insert: "\n" | header: 2 | Same for H2–H6 |
| insert: "\n" | list: "ordered" | |
| insert: "\n" | list: "bullet" | |
| insert: "\n" | list: "checked" or list: "unchecked" | Slab uses task lists |
| insert: "\n" | indent: N | Delta uses flat indent levels (0, 1, 2…); you must reconstruct nested <ul> trees |
| insert: "\n" | blockquote: true | |
| insert: "\n" | code-block: "python" | Language tag may be absent |
| insert: {image: "url"} | — | URL points to Slab CDN; must download and re-host |
| insert: {video: "url"} | — | No native video embed in Guru |
| insert: {slab-embed: {...}} | type: "github", type: "figma", etc. | Slab-proprietary; no Guru equivalent. Convert to descriptive hyperlink |
| insert: {table: [...]} | — | Slab's table Delta format is non-standard; requires custom parsing |
| insert: {divider: true} | — |
Slab Guru
| Slab field | Guru field | Notes |
|---|---|---|
| post.title | card.preferredPhrase | Direct copy. Must be unique or appended with context. |
| post.content (Quill Delta) | card.content (HTML) | Quill Delta → HTML conversion using operation mapping. Split if exceeds ~50K chars. |
| post.topics [0] (primary) | card.collection.id | Map via topic → collection lookup. |
| post.topics [1..n] (secondary) | card.tags [] | Topic name → Tag. |
| post.owner.email | card.verifiers [0].user.email | Direct mapping. |
| post.insertedAt | Not directly settable | Guru sets creation timestamp automatically. |
| post.updatedAt | Not directly settable | Guru tracks its own update timestamps. |
| Topic hierarchy (parent → child) | Collection → Folder | Parent topic = Collection; child topic = Folder. Flatten beyond 3 levels. |
| Post visibility (public/secret/restricted) | Collection group permissions | Public → All Members group; Secret → dedicated restricted group; Restricted → specific group matching invited members. |
| Inline images | Card images (re-hosted URLs) | Download → re-upload → replace URLs. |
| Internal post links | Internal Card links | URL rewrite using ID mapping table. |
Risk matrix
Per-object risk for this pair. Plan extra validation around anything marked high.
| Object | Risk | Notes |
|---|---|---|
| Posts / Cards | medium | Post content migrates with moderate risk; plain text transfers reliably, but rich formatting, embedded content, and Quill Delta-specific elements require careful conversion to Guru's HTML card format to avoid data loss or rendering issues. |
| Topic Hierarchy | high | Slab's multi-level, many-to-many topic structure has no direct equivalent in Guru's three-level Collections → Folders → Cards hierarchy, requiring custom mapping logic and inevitably forcing organizational decisions that alter the original content architecture. |
| Internal Links | high | All internal cross-post links break during migration because Slab and Guru use entirely different ID and URL schemes, and repairing them requires maintaining a complete Slab post ID to Guru Card ID mapping table throughout the pipeline. |
| Attachments | medium | File attachments hosted on Slab's CDN must be individually downloaded and re-uploaded to Guru during migration, and any CDN URLs embedded in post content will become broken references if not systematically replaced. |
| Rich Embeds | high | Embeds from third-party tools such as GitHub, Figma, and Loom are not preserved through Markdown export and require per-embed-type handling in an API pipeline, with no guaranteed equivalent embed support in Guru's card format. |
| Permissions and Access Control | medium | Slab manages access at the topic level with public, secret, and restricted options, while Guru enforces permissions at the collection and folder level via user groups, requiring a deliberate re-mapping of access control that may not translate one-to-one. |
| Verification Metadata | medium | Verification owner assignments, review intervals, and last-verified timestamps are not included in any Slab export format and must be reconstructed manually or via the Guru API, risking loss of accountability history if not explicitly planned for. |
| Secret Topic Content | high | Posts within secret topics not shared with the exporting admin are silently excluded from Slab's export, creating a risk of undetected content loss that requires a pre-migration audit of all secret topics and their membership before extraction begins. |
| Users and Ownership | medium | Post authorship and ownership metadata from Slab must be matched to corresponding Guru user accounts by email or identifier, and any mismatches — such as deprovisioned users — will result in cards with unassigned or incorrect ownership in Guru. |
| Tags | low | Guru has a dedicated tag system separate from its folder hierarchy, so Slab topic labels that do not become primary collections can be mapped to Guru tags with relatively low transformation complexity and low risk of data loss. |
The hard parts
What makes this specific migration difficult, beyond the mechanics.
Many-to-Many Topic Mapping
Slab posts can belong to multiple topics simultaneously, but Guru cards must reside in a single primary collection, requiring a deliberate decision on which topic becomes the canonical collection and which become tags or Board placements.
Quill Delta to HTML Conversion
Slab stores post content internally in Quill Delta JSON format, which requires a dedicated parser to convert accurately into the HTML format that Guru's editor and API consume.
Internal Link Integrity
Cross-references between Slab posts use Slab-specific post IDs and URL structures that break entirely during migration, requiring a maintained ID mapping table to programmatically rewrite every internal link to its corresponding Guru Card URL.
Embedded Integration Content Loss
Rich embeds from GitHub, Figma, Loom, and similar integrations do not survive the Markdown export process and are either dropped or reduced to bare URLs, requiring manual reconstruction or custom API handling per embed type.
Secret Topic Visibility Gap
Slab admins can only export content they have explicit permission to view, meaning posts in secret topics not shared with the exporting admin will silently fail to export and be lost if not discovered in advance.
Verification Metadata Preservation
Slab's per-post verification ownership data — including assigned owner, verification interval, and last verified date — is not carried through any export format and must be reconstructed and set explicitly via Guru's API during migration.
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
Can I migrate directly from Slab to Guru?
There's no one-click migration. Guru has a Slab import option, but it only accepts Markdown files from Slab's manual export. This works for small workspaces but loses topic hierarchy, verification metadata, and internal links. For larger migrations, you need an API-based pipeline.
Does Slab have an API for data extraction?
Yes, Slab offers a GraphQL API, but it's only available on Business ($12.50/user/mo) or Enterprise plans. The API supports querying posts, topics, and content using cursor-based pagination. Free and Startup plan users are limited to the manual Markdown/Docx export.
How do Slab Topics map to Guru Collections?
Slab allows multiple topics per post (many-to-many), while Guru requires each Card to belong to exactly one Collection. Map the primary Slab topic to a Guru Collection and convert secondary topics to Guru Tags. Sub-topics can become Folders within the Collection, up to three nesting levels.
What content gets lost during a Slab to Guru migration?
Potential losses include: embedded third-party content (GitHub, Figma, Loom embeds), version history (Slab doesn't export it), inline images if not re-hosted, internal links if not rewritten, secret topic content if the migration account lacks access, and drafts (not included in manual export).
What are Guru's API rate limits for migration?
Guru enforces rate limits per account but does not publicly document specific numeric thresholds. You'll receive HTTP 429 responses when you hit the limit. Build your migration script with exponential backoff and start conservatively at 1-2 requests per second.