{"schemaVersion":1,"title":"Authors, reviews and edit links","url":"https://appgram.github.io/docsy/guides/tutorials/authors-and-edit-links","markdownUrl":"https://appgram.github.io/docsy/format-md/guides/tutorials/authors-and-edit-links","jsonUrl":"https://appgram.github.io/docsy/agent/pages/guides/tutorials/authors-and-edit-links.json","version":"current","locale":"en","markdown":"# Authors, reviews and edit links\n\nCredit authors and contributors, link to GitHub edits, and optionally record coding-agent provenance without claiming an automatic quality score.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nContributors: Docsy coding agent (coding agent)\n\nUpdated: 2026-10-19\n\nAgent provenance: Docsy coding agent (coding agent)\n\nDocsy keeps article attribution in `docsy.config.yaml`, for both Markdown and MDX. Profiles are reusable; each version/language registration decides who wrote, contributed to or reviewed that particular text.\n\n## Register author profiles\n\n```yaml\nauthors:\n  alex:\n    name: Alex Morgan\n    kind: human\n    github: your-github-username\n    role: Documentation maintainer\n    avatar: assets/authors/alex.png\n  platform-team:\n    name: Platform team\n    kind: organization\n    url: https://example.com/team\n  docs-agent:\n    name: Your coding agent\n    kind: agent\n    provider: Your agent provider\n```\n\nThese names and IDs are examples, not claims about this project's contributors. Omit fields you do not need. `kind` defaults to `human`; the other choices are `organization` and `agent`. `github` is a username or organization name, not a repository URL. An explicit HTTP(S) `url` overrides the derived GitHub profile link. `role` appears as a profile tooltip.\n\nAvatars are optional for human, team and coding-agent profiles. Local `assets/...` paths follow `site.basePath`; place the file in `public/assets/`. No avatar is fetched from GitHub automatically. Remote HTTP(S) avatars are used only when explicitly configured, and will contact that external host. Never place private images in `public/`.\n\n## Configure profile pictures and unknown authors\n\nProfiles with `kind: organization` appear as compact logo-and-name tags beside the other credited profiles. Use a short `name` such as `AppGram` for the tag label and `url: https://appgram.dev` for its link destination; the domain does not need to be the displayed name.\n\n```yaml\nauthors:\n  alex:\n    name: Alex Morgan\n    avatar: assets/authors/alex.png\n  docs-agent:\n    name: Your coding agent\n    kind: agent\n    avatar: assets/authors/docsy-agent.svg\nreader:\n  defaultAuthorAvatar: assets/authors/unknown.svg\n  unknownAuthorAvatar: assets/authors/unknown.svg\n```\n\nEach known author's `avatar` takes priority. `reader.defaultAuthorAvatar` is an optional shared picture for registered authors who have no individual image. Without either, Docsy retains initials or a generic coding-agent icon. Images are cropped into the existing circular byline; a failed image falls back to initials or the local icon rather than leaving a broken picture.\n\nThe bundled `assets/authors/unknown.svg` is a neutral outlined placeholder rendered with the current theme's text, surface and border colours, not a fixed light or blue background. Custom photos and other image URLs retain their original colours.\n\n`reader.unknownAuthorAvatar` is a separate opt-in: an article with no `authors` displays this image and the label “Unknown author.” This does not create a person in the author registry, structured data, search or Markdown/JSON exports, or infer an author from contributors or agent provenance. Unknown author IDs still fail validation, so a typo cannot silently turn a credited writer into an anonymous one. Omitting `unknownAuthorAvatar` leaves unauthored articles without a writer byline. `reader.showByline: false` hides both known and unknown bylines.\n\nBoth fallback settings accept a local asset or an explicit HTTP(S) image URL, just like profile `avatar`. Neither fallback is enabled automatically. Change the unknown label through `localization.messages.<locale>.unknownAuthor`; the bundled portal supplies Spanish and French labels too. These public image URLs are not protected by article access rules.\n\n## Credit an article\n\n```yaml\ncontent:\n  articles:\n    - slug: authentication\n      source: content/authentication.md\n      title: Authentication\n      authors: [alex]\n      contributors: [docs-agent, platform-team]\n      reviewedBy: [alex]\n      publishedAt: '2026-10-01'\n      updatedAt: '2026-10-19'\n      reviewedAt: '2026-10-19'\n```\n\nUse `authors` for the byline, `contributors` for assistance and `reviewedBy` for a recorded review. All lists are optional and preserve their configured order. Unknown IDs and duplicate IDs in a list fail validation. Leaving the fields out produces no author/date claims. You can credit an agent as the writer, rather than a contributor, by putting its ID in `authors`.\n\nQuote dates as `YYYY-MM-DD`. Invalid calendar dates, an update before publication, or a review date without any reviewer fail validation. Dates are formatted in the reader's UI language using UTC. They are never taken from filesystem modification times or automatically advanced on build.\n\nAttribution on a fallback article comes from the selected source registration, not a guessed translator. To credit a translator, add them to that locale registration's `contributors`. Version-specific authorship does not inherit another version's metadata.\n\n## Add the optional edit button\n\n```yaml\nreader:\n  showByline: true\n  editEnabled: true\n  editPlacement: footer\n  editStyle: subtle\n  editUrl: https://github.com/OWNER/REPOSITORY/edit/main/{source}\n  reportUrl: https://github.com/OWNER/REPOSITORY/issues/new\n```\n\nThe edit link appears below the article body by default, alongside the optional report link. `editStyle: subtle` uses muted text and a small pencil icon with no button border; hover and keyboard focus keep it discoverable. To restore a bordered control, use `editStyle: button`. To place it beside the author credits instead, use `editPlacement: header`. These settings work independently, default to `footer` and `subtle`, and apply to all article versions and languages.\n\nIt opens GitHub's existing edit flow; Docsy does not authenticate to GitHub, grant repository access, commit edits or create a pull request itself. GitHub determines what the reader can do. A private repository still requires the appropriate GitHub access.\n\n`{source}` expands to the selected article's source path, encoding each path segment. `{version}` and `{locale}` are also supported, but are documentation context IDs—not automatically Git branches or directory names. For a branch literally named `main`, keep `main` in the template as above. Paths for translations follow their actual `source` values, including when a locale falls back to another language.\n\nThe author profile's `github` setting is independent: writers may have personal profiles while the edit button points to an organization-owned documentation repository. No edit link is inferred from an author, source host or `site.githubUrl`. Generated projects using the CLI's `--repo` option already get explicit edit/report URL templates.\n\nTo disable all edit buttons without removing the template:\n\n```yaml\nreader:\n  editEnabled: false\n```\n\nTo hide or override a particular page's edit link, set one of these fields on its article registration:\n\n```yaml\n# Under the chosen content.articles item:\neditUrl: false\n# Or, instead:\n# editUrl: https://github.com/OWNER/OTHER-REPOSITORY/edit/main/{source}\n```\n\nA global `editEnabled: false` always wins. An unset page-specific URL uses `reader.editUrl`; removing both URL settings leaves the button absent. Report links remain independent and include the canonical page URL, version and language, not visitor authentication/search query parameters.\n\n## Record agent provenance without inventing a score\n\n```yaml\n# Under the chosen content.articles item:\nauthors: [alex]\ncontributors: [docs-agent]\nprovenance:\n  agent: docs-agent\n  model: YOUR_ACTUAL_MODEL_ID\n  referenceUrl: https://github.com/OWNER/REPOSITORY/pull/123\n```\n\nAll provenance is optional. `agent` must reference a registered `kind: agent` profile. `model` records the identifier you actually used; Docsy does not guess it. `referenceUrl` can point to a reviewable pull request or agent run. This is a reference to evidence, not an automatic verification of that evidence.\n\nFor a fully agent-written page, put the agent in `authors` instead. For assistance, keep the writer in `authors` and use `contributors` or provenance. A configured reviewer is displayed as a reviewer, not as a Docsy-certified approval. Never claim a human review that did not happen.\n\nThere is no automatic confidence, accuracy or quality score. Build/link validation cannot establish those properties, and an agent's self-reported confidence is not a useful guarantee. The numeric `score` in the agent search API is search relevance, not documentation quality.\n\nThe maintenance workflow preserves existing authors, contributors, reviewers, dates, provenance and per-page edit URLs. The agent cannot add those claims to a newly registered page either. A maintainer records them deliberately after reviewing the change; the workflow does not manufacture approvals or silently advance review dates.\n\n## Visibility, exports and access\n\n`reader.showByline: false` hides author, date and provenance UI; it does not remove configured metadata from Markdown/JSON exports. To stop publishing an identity, remove its article references. Unused profiles are not exposed through a global author directory.\n\nThe article JSON endpoint includes structured `authorship` and the resolved optional `editUrl`. Markdown exports include readable author/reviewer/date/provenance lines. Full-text search can find an article by a credited name. These surfaces keep the existing article permission checks: a locked article's identity and provenance must not leak through public search or JSON exports.\n\nHuman and organization writers also appear in article structured data. Agents are never labeled as people there; their optional attribution remains explicit in the byline and Markdown/JSON metadata. Profile names are configured project data, not verified legal identities. Imported API/SDK reference pages continue to describe upstream generator content; Docsy does not invent local authors for those pages.\n\n## What to check before publishing\n\n1. Use real profile IDs and only claim dates/reviews you can substantiate.\n2. Check the GitHub edit URL against each selected source, version and language.\n3. Leave model/run references out when you do not know them.\n4. Verify anonymous and authorized search, Markdown and JSON output for restricted articles.\n5. Run `npm run validate` and `npm run build`, and inspect both themes.\n\nPer-page edit opt-outs and explicit date overrides are established documentation patterns; [Starlight documents both](https://starlight.astro.build/reference/frontmatter/#editurl). Docsy's configuration above deliberately stays in YAML rather than silently reading article frontmatter or Git history.\n\n","contentLocale":"en","isFallback":false,"authorship":{"authors":[{"name":"nedimf","kind":"human","github":"nedimf","avatar":"/docsy/assets/authors/nedimf.png","role":"AppGram","id":"nedimf","url":"https://github.com/nedimf"},{"name":"AppGram","kind":"organization","github":"AppGram","url":"https://appgram.dev","avatar":"/docsy/assets/ag-logo.svg","id":"appgram"}],"contributors":[{"name":"Docsy coding agent","kind":"agent","avatar":"/docsy/assets/authors/docsy-agent.svg","provider":"OpenAI","id":"docsy-agent"}],"reviewedBy":[],"updatedAt":"2026-10-19","provenance":{"agent":{"name":"Docsy coding agent","kind":"agent","avatar":"/docsy/assets/authors/docsy-agent.svg","provider":"OpenAI","id":"docsy-agent"}}},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/authors-and-edit-links.md"}