> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # Yuque > Configure the Yuque connector and limit indexing to explicitly approved repositories and attachments. The Yuque connector brings approved Yuque knowledge-base pages and optional attachments into AIvis retrieval. It is scoped by repository path and reads only repositories explicitly entered by an administrator. ## Use cases | Scenario | Recommendation | | -------------------------- | ---------------------------------------------------------------------- | | Product documentation Q\&A | Create one connector per product knowledge base. | | Project wiki retrieval | Use separate connectors and document sets per project space. | | Engineering policy lookup | Sync only published policy documents intended for the target audience. | | Attachment retrieval | Enable attachments only when files are approved and parseable. | | Mixed-permission spaces | Split repositories or connectors by audience. | ## What it indexes | Yuque data | Indexing behavior | | --------------- | --------------------------------------------------------------------------------------------------------------------------- | | Pages | Reads document lists and details, converts HTML bodies to searchable text, and stores title, updated time, and source link. | | Hierarchy nodes | Emits each page as a page node so search results identify the source. | | Attachments | Optional child documents under their parent Yuque pages. | The connector accepts 1 to 100 unique repositories in `namespace/slug` format. It does not index unlisted repositories, team membership, comments, collaboration history, drafts, trash, export packages, or space-level analytics. ## Prerequisites * Prepare a Yuque token that can read the target repositories. * Collect repository paths such as `acme/product-handbook` from Yuque URLs. * Confirm the token account can read document details and attachment download URLs. * Decide whether attachments should be indexed. * Decide the AIvis access group before indexing private content. * Allow the AIvis backend to reach `www.yuque.com`. ## Where to get configuration values | Configuration value | Where to get it | | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Yuque token | Sign in to Yuque and create a dedicated token from the [Token settings page](https://www.yuque.com/settings/tokens). Grant only the permissions needed for indexing. | | Repository path `namespace/slug` | Open the target repository and take `{namespace}/{slug}` from `https://www.yuque.com/{namespace}/{slug}`. You can also use the [Yuque developer documentation](https://www.yuque.com/yuque/developer/api) to verify repository / docs API path parameters. | | Document detail and attachment readability | Use the same token against Yuque document-detail APIs, or open the target document in Yuque, to confirm the token owner can read the body and attachment download URLs. | ## Configure in AIvis In the Admin panel, open **Connectors**, select **Yuque**, create or choose a Yuque credential, and then enter repository paths and the attachment switch. | Field | How to fill it | Notes | | ------------------- | -------------------------------------------------------------- | ------------------------------------------------------ | | Yuque token | Paste a dedicated token | Used for Yuque API access. | | Yuque repositories | One `namespace/slug` per line, such as `acme/product-handbook` | Only listed repositories are indexed. | | Include attachments | Enabled by default | Reads parseable attachments found in document details. | Do not enter a full URL, profile URL, or namespace-only value. Each repository path must contain both namespace and repository slug. ## Sync behavior The standard Admin-created Yuque connector runs as a polling connector with checkpoint resume. | Stage | Behavior | | ------------------ | ------------------------------------------------------------------------------ | | Document list | Reads summaries for each configured repository and builds a stable inventory. | | Document detail | Fetches each page detail and converts HTML body content into searchable text. | | Attachments | Emits attachments as child documents; each page is capped at 1000 attachments. | | Incremental window | Pages outside the sync updated-time window are skipped. | Attachment URLs must be safe HTTPS URLs. Documents or attachments that cannot be processed are recorded as item failures. ## Permissions The Yuque token determines what AIvis can ingest, but this connector does not synchronize Yuque organizations, teams, repository members, or per-page permissions into AIvis. | AIvis access setting | Meaning | | -------------------- | ---------------------------------------------------------------------------------------------------------------------- | | Private groups | Only selected AIvis groups can search documents produced by this connector. Recommended for internal repositories. | | Public | Every eligible AIvis user can search indexed content. Use only for repositories that can be shared with that audience. | | Auto permission sync | Yuque is not supported for this mode. | Use AIvis **Private** groups for internal repositories. Use **Public** only when every eligible AIvis user may search every indexed page and attachment. Yuque is not available as an auto permission-sync source. ## Verify 1. Create a connector with one test repository. 2. Search known page titles, body keywords, and source links. 3. If attachments are enabled, upload a small parseable attachment and confirm it is searchable. 4. Search unlisted repositories or private pages and confirm they are absent. 5. Test assigned and outside AIvis users. 6. Modify a test page and confirm the next sync updates it. ## Troubleshooting | Symptom | What to check | | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- | | Authentication fails | Token value, expiration, and revocation state. | | Repository validation fails | Repository path must be `namespace/slug` and readable by the token account. | | Pages are empty or missing | Check that the page is in the configured repository, within the sync window, and readable via detail API. | | Attachments are missing | Check the attachment switch, download URL reachability, file type, and size. | | Users can search content they should not see | Restrict AIvis access groups or split connectors by repository/audience. | ## Security and maintenance * Use a dedicated Yuque token instead of a broad personal token. * Review repository list, attachment switch, token owner, and AIvis groups regularly. * Rotate or revoke the token if it may have leaked. * Update and revalidate the connector after repository moves, renames, or permission changes. * Disable the connector before revoking unused tokens. ## Official references * [Yuque developer documentation](https://www.yuque.com/yuque/developer/api) ## Related pages * [Connectors & Indexing](/aivis/knowledge/connectors) * [Index Settings](/aivis/knowledge/index-settings) * [Users, Groups & Roles](/aivis/governance/users-and-groups)