{"schemaVersion":1,"title":"Write authored documentation","url":"https://appgram.github.io/docsy/versions/current/fr/guides/tutorials/authored-articles","markdownUrl":"https://appgram.github.io/docsy/format-md/versions/current/fr/guides/tutorials/authored-articles","jsonUrl":"https://appgram.github.io/docsy/agent/pages/versions/current/fr/guides/tutorials/authored-articles.json","version":"current","locale":"fr","markdown":"# Write authored documentation\n\nAdd Markdown guides and articles beside generated API and SDK reference pages.\n\nWritten by: [nedimf](https://github.com/nedimf), [AppGram](https://appgram.dev)\n\nAuthored articles let a Docsy site contain onboarding, concepts, tutorials, migration notes, and operational guides beside generated API and SDK reference pages.\n\nThe article body can be Markdown (`.md`) or native MDX (`.mdx`). YAML supplies route and presentation metadata. [Native MDX articles](../native-mdx) add built-in JSX components and optional trusted React modules without changing navigation, search, exports or permissions.\n\n## Create the Markdown source\n\nCreate a file anywhere outside `public/`. Keeping authored content under `content/` makes the boundary obvious:\n\n```text\ncontent/\n└── guides/\n    └── authentication.md\n```\n\nWrite the body as ordinary Markdown. The page title and description come from YAML, so the source can begin at level two:\n\n````markdown\nUse a bearer token when calling protected endpoints.\n\n## Create a token\n\nOpen the dashboard and create a token for the target environment.\n\n## Send a request\n\n```bash\ncurl https://api.example.com/me \\\n  --header 'Authorization: Bearer <token>'\n```\n````\n\nDocsy renders headings, links, lists, blockquotes, tables, inline code, fenced code blocks, and trusted inline HTML. Level-two and level-three headings populate the right-hand table of contents.\n\n## Register the article in YAML\n\nAdd the source to `content.articles`:\n\n```yaml\ncontent:\n  articles:\n    - slug: authentication\n      source: content/guides/authentication.md\n      title: Authentication\n      description: Create a token and authenticate API requests.\n      eyebrow: GUIDE\n```\n\nThe `slug` becomes `/guides/authentication`. Nested slugs create nested URLs:\n\n```yaml\n- slug: platform/security/authentication\n  source: content/guides/authentication.md\n  title: Authentication\n```\n\nThat article is served at `/guides/platform/security/authentication` underneath `site.basePath`.\n\n## Place it in navigation\n\nRegistration creates the route. Navigation is explicit so you control grouping and order:\n\n```yaml\nnavigation:\n  - title: Platform\n    items:\n      - title: Security\n        href: /guides/platform/security/authentication\n        items:\n          - title: Authentication\n            href: /guides/platform/security/authentication\n```\n\nNavigation entries do not create pages by themselves. Their `href` must point to an authored article, API section, SDK page, or Astro route that exists.\n\n## Credit writers and let readers correct a page\n\nRegister reusable profiles under `authors`, then reference their IDs in each article's `authors`, `contributors` or `reviewedBy` arrays. Human, organization and coding-agent profiles are supported. Publication/update/review dates and optional agent provenance are explicit YAML metadata, not inferred from Git commits or build dates.\n\nSet `reader.editUrl` to your repository's edit URL template to show an **Edit this page** button. An article's `editUrl: false` disables it for that page, or a page-specific URL overrides the template. Author GitHub profiles and the documentation repository are separate settings.\n\nSee [Authors, reviews and edit links](../authors-and-edit-links) for complete YAML examples, optional agent/model references, and export/privacy behavior.\n\n## Search and Markdown export\n\nRegistered articles automatically participate in:\n\n* Full-site search, including article headings.\n* The on-page heading rail.\n* `?format=md` and `/format-md/...` exports for agents and LLM tools.\n* Lock-mode rules and search-result filtering.\n\nFor example, `/docs/guides/authentication?format=md` resolves to the article's Markdown export when the site uses `/docs` as its base path.\n\n## Protect an article\n\nAuthored articles use the same access rules as generated reference pages:\n\n```yaml\naccess:\n  mode: locked\n  rules:\n    - pattern: /guides/internal/**\n      tiers: [enterprise]\n```\n\nKeep protected Markdown outside `public/`. Files in `public/` are static assets and bypass request-time permission checks.\n\nNext: [ingest an OpenAPI document](../openapi-ingestion).\n\n","contentLocale":"en","isFallback":true,"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":[],"reviewedBy":[]},"editUrl":"https://github.com/AppGram/docsy/edit/main/content/tutorials/authored-articles.md"}