{"id":15513429,"url":"https://github.com/adonisjs/v5-docs","last_synced_at":"2025-05-16T15:06:38.691Z","repository":{"id":37035898,"uuid":"366022780","full_name":"adonisjs/v5-docs","owner":"adonisjs","description":"📚 Source code and documentation for the official docs website. ","archived":false,"fork":false,"pushed_at":"2025-02-25T17:54:28.000Z","size":4226,"stargazers_count":89,"open_issues_count":21,"forks_count":139,"subscribers_count":9,"default_branch":"develop","last_synced_at":"2025-04-12T14:16:56.661Z","etag":null,"topics":["adonisjs","documentation","hacktoberfest"],"latest_commit_sha":null,"homepage":"https://v5-docs.adonisjs.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/adonisjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"thetutlage"}},"created_at":"2021-05-10T11:42:24.000Z","updated_at":"2025-04-04T03:46:06.000Z","dependencies_parsed_at":"2023-09-30T14:40:59.385Z","dependency_job_id":"30f7c148-eac8-409b-bb5c-6176f3f0b50b","html_url":"https://github.com/adonisjs/v5-docs","commit_stats":null,"previous_names":["adonisjs/docs.adonisjs.com"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonisjs%2Fv5-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonisjs%2Fv5-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonisjs%2Fv5-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/adonisjs%2Fv5-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/adonisjs","download_url":"https://codeload.github.com/adonisjs/v5-docs/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254553959,"owners_count":22090417,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["adonisjs","documentation","hacktoberfest"],"created_at":"2024-10-02T09:54:17.939Z","updated_at":"2025-05-16T15:06:38.671Z","avatar_url":"https://github.com/adonisjs.png","language":"TypeScript","funding_links":["https://github.com/sponsors/thetutlage"],"categories":["TypeScript"],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://res.cloudinary.com/adonisjs/image/upload/q_100/v1558612869/adonis-readme_zscycu.jpg\" width=\"600px\"\u003e\n\u003c/div\u003e\n\n\u003cbr /\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003ch3\u003eAdonisJS official documentation\u003c/h3\u003e\n  \u003cp\u003eSource code and documentation for the official documentation website hosted on \u003ca href=\"https://docs.adonisjs.com\"\u003edocs.adonisjs.com\u003c/a\u003e\u003c/p\u003e\n\u003c/div\u003e\n\n## Setup\nFollow the below mentioned steps to setup the project on your local.\n\n- Fork the repo\n- Pull the repo on your local\n- Install all dependencies using `npm install`.\n- Start the AdonisJS development server using `node ace serve --watch`\n\n**We do not follow any build process for rendering markdown to HTML**. Instead, we compile markdown files on every page request. This ensures, we do not have to run any background compilers to compile markdown and then re-compile everything on a single change. The process is as simple as\n\n```\n--\u003e New HTTP request --\u003e Finding markdown file for the url --\u003e Compile and serve it\n```\n\n## Environment variables\n\nFollowing environment variables are required to start the development server or create the production build.\n\n```\nPORT=3333\nHOST=0.0.0.0\nNODE_ENV=development\nAPP_KEY=iPbHJ0Wdr8_hA4DLTj83lKedQP9I5rJO\nCACHE_VIEWS=false\nDEBUG_DOCS=true\nALGOLIA_API_KEY=\nCOPY_REDIRECTS_FILE=false\nREPOSITORY_URL=https://github.com/adonisjs/docs.adonisjs.com\n```\n\nThe `ALGOLIA_API_KEY` environment variable is optional and required only if you want to enable search.\n\nIf you are deploying a translated version of the docs, then set the `COPY_REDIRECTS_FILE=false`. Since the redirects file is applicable only for the official documentation to avoid breaking the `preview.adonisjs.com` URLs.\n\n## Content structure\n\nThe markdown content is saved inside the `content` directory and each documentation type (we call them zones) has its own subfolder. \n\nThe navigation for the website header and the sidebar is driven by the `menu.json` file inside each zone's subdirectory.\n\n```\ncontent\n├── cookbooks\n│   ├── menu.json\n├── guides\n│   ├── menu.json\n├── reference\n│   └── menu.json\n└── releases\n    ├── menu.json\n```\n\nThe `menu.json` file has the following structure\n\n```json\n{\n  \"name\": \"Database\",\n  \"categories\": [\n    {\n      \"name\": \"root\",\n      \"docs\": [\n        {\n          \"title\": \"Connection\",\n          \"permalink\": \"database/connection\",\n          \"contentPath\": \"database/connection.md\",\n        }\n      ]\n    }\n  ]\n}\n```\n\n- The top level object is the group name. You can have one or more groups inside a zone and they will be listed in a dropdown in the header nav.\n- If there is no only one group. You can name it as `root`.\n- Each group can have one or more `categories`. The categories are listed inside the sidebar.\n- The category with name `root` will not be printed in the HTML.\n- Each category can have one or more `docs`.\n- The docs further have a `title`, `permalink` and the path to the content file. **The path is relative from the zone root.**\n\n## Rendering HTML\n\nWe make use of a self written [@dimerapp/content](https://npm.im/@dimerapp/content) module to render markdown to HTML using Edge templates in the middle.\n\nWe begin by first converting Markdown to an AST and then render each node of the AST using Edge templates. This allow to spit custom markup. Checkout the [./resources/views/elements](./resources/views/elements) directory to see how we are using it.\n\nThe code blocks are rendered using the [shiki](https://github.com/shikijs/shiki). The module uses VsCode grammar and themes to process the code blocks. Also, code blocks are processed on the backend and the client receives formatted HTML.\n\n\n## Configuring `@dimerapp/content`\n\nThe `@dimerapp/content` module does not come with any CLI or opinions on how the content should be structured. \n\nSo we have to self configure `@dimerapp/content` module. This is done inside the `start/content.ts` file, which relies on the `config/markdown.ts` file.\n\n\n## CSS and frontend JavaScript\n\nThe styles are written in Vanilla CSS and stored inside the `./resources/css` directory. To organize things a bit, we have split them inside multiple `.css` files.\n\nWe also make use of Alpine.js for adding small interactive components, like the header nav dropdown and the codegroup toggle.\n\nThe `@hotwire/turbo` is used to navigate between pages without doing a complete refresh.\n\n### Custom JS Hacks\n\nRe-rendering HTML pages resets the scroll position of the sidebar, which is kind of annoying. So we make use of turbo  events `turbo:before-render` and `turbo:render` to store the sidebar position and then restore it after navigation.\n\nOn first page visit, we scroll the active sidebar item into the view using the `scrollIntoView` method.\n\n## Deployment\n\nRun the following command to create the production build. \n\n```\nnpm run build\n```\n\nThe output is written to the `public` directory and you can deploy it on any host capable of serving static files.\n\nThe official website is hosted on [pages.cloudflare.com](https://pages.cloudflare.com/)\n\n### Important environment variables\n\nThe `ALGOLIA_API_KEY` environment variable is optional and required only if you want to enable search.\n\nIf you are deploying a translated version of the docs, then set the `COPY_REDIRECTS_FILE=false`. Since the redirects file is applicable only for the official documentation to avoid breaking the `preview.adonisjs.com` URLs.\n\n## Translating docs to different languages\n\nYou are free to fork this repo and translate docs to different languages and publish them on a separate subdomain.\n\n\u003e Disclaimer: The translated documentation is considered a community effort. The website and translations are/will never be supported or maintained by the core team.\n\n### Process for translating docs\n\n- Notify everyone about the translated docs on this [pinned issue](https://github.com/adonisjs/docs.adonisjs.com/issues/1).\n- We can issue you a subdomain for the language once you have translated more than 50% of the docs.\n- As the documentation is updated on the official website, we will drop a link to the PR on the [pinned issue](https://github.com/adonisjs/docs.adonisjs.com/issues/1) and you can pull back those changes.\n- We recommend not localizing the URLs. Just translate the docs content.\n- Feel free to send a PR to Algolia for indexing the translated website. Here is a [reference to algolia config](https://github.com/algolia/docsearch-configs/blob/master/configs/adonisjs_next.json) for the official website.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadonisjs%2Fv5-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fadonisjs%2Fv5-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fadonisjs%2Fv5-docs/lists"}