{"id":26279694,"url":"https://github.com/alephdata/astro-theme-docs","last_synced_at":"2025-03-14T14:16:03.505Z","repository":{"id":75307182,"uuid":"569790652","full_name":"alephdata/astro-theme-docs","owner":"alephdata","description":null,"archived":false,"fork":false,"pushed_at":"2025-02-12T05:25:42.000Z","size":792,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-02-12T06:39:12.040Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Astro","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/alephdata.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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}},"created_at":"2022-11-23T16:09:22.000Z","updated_at":"2025-02-12T05:25:45.000Z","dependencies_parsed_at":"2025-02-12T06:27:36.276Z","dependency_job_id":"5fdf2784-d8d4-4a04-9d2e-9ad312bcea67","html_url":"https://github.com/alephdata/astro-theme-docs","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alephdata%2Fastro-theme-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alephdata%2Fastro-theme-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alephdata%2Fastro-theme-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alephdata%2Fastro-theme-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alephdata","download_url":"https://codeload.github.com/alephdata/astro-theme-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243589321,"owners_count":20315471,"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":[],"created_at":"2025-03-14T14:16:01.002Z","updated_at":"2025-03-14T14:16:03.468Z","avatar_url":"https://github.com/alephdata.png","language":"Astro","readme":"# astro-theme-docs\n\nThis repository contains a custom theme and a set of reusable components for [Astro](https://astro.build), a static site generator (SSG). We use this as the foundation for multiple documentation sites the OCCRP Aleph team maintains (including [Aleph](https://docs.aleph.occrp.org), [FollowTheMoney](https://alephdata.github.io/followthemoney), and [Memorious](https://alephdata.github.io/memorious)).\n\nAstro is a generic SSG and (unlike projects like MkDocs or mdBook) isn’t intended to be used for documentation sites exclusively. The advantage of this approach is that we have more flexibility to customize how the documentation is rendered and can for example include interactive elements in the documentation or auto-generate pages. For example, we auto-generate a documentation page for every schema ([like this one](https://alephdata.github.io/followthemoney/explorer/schemata/Company/)) in the FollowTheMoney data model based on the schema definition.\n\nThe main disadvantage of this approach is that we have had to implement a few features ourselves that are common to every documentation site (for example, navigation, multi-column layout, …). This repository exists to share the boilerplate between all of our documentation sites.\n\n## Seting up a new site\n\nBootstrap a new Astro project following the steps in the [Astro documentation](https://docs.astro.build/en/install/manual/).\n\n### 1. Install\n\n```\nnpm install github:alephdata/astro-theme-docs\n```\n\n### 2. Configure\n\nAdd the theme to the Astro configuration in `astro.config.mjs`:\n\n```diff\n  import { defineConfig } from 'astro/config';\n+ import theme from 'astro-theme-docs';\n  \n  // https://astro.build/config\n  export default defineConfig({\n+   integrations: [theme()],\n  });\n```\n\nCreate `src/options.json` based on the following example and customize the options:\n\n```jsonc\n{\n  // The site title\n  \"title\": \"Aleph\",\n  \n  // These options are used to display the date was last updated and to generate\n  // links to edit a page on GitHub.\n  \"git\": {\n    \"branch\": \"main\",\n    \"githubRepoUrl\": \"https://github.com/alephdata/aleph\"\n  },\n  \n  // Configure which pages appear in which order in the sidebar navigation.\n  \"nav\": {\n    \"sidebar\": {\n      \"sections\": [\n        {\n          \"title\": \"Getting Started\",\n          \"items\": [\n            // The title and URL of the navigation item is generated automatically\n            // based on the page contents.\n            { \"slug\": \"/about\" }\n          \n            {\n              \"slug\": \"/installation\",\n              \"children\": {\n                // Pages can be nested. Nesting is limited to one level.\n                { \"slug\": \"/installation/development\" },\n                { \"slug\": \"/installation/production\" },\n              },\n            },\n            \n            // Linking to external pages.\n            {\n              \"title\": \"API Reference\",\n              \"link\": \"https://example.org\",\n              \"external\": true\n            }\n          ]\n        }\n      }\n    }\n  }\n}\n```\n\n### 3. Create a layout\n\nCreate `src/layouts/DocsLayout.astro`:\n\n```astro\n---\nimport { DocsLayout } from 'astro-theme-docs/components';\nimport options from '../options.json';\n---\n\n\u003cDocsLayout {options} {...Astro.props}\u003e\n  \u003cslot /\u003e\n  \u003cslot name=\"sidebar\" slot=\"sidebar\" /\u003e\n  \u003cslot name=\"meta\" slot=\"meta\" /\u003e\n  \u003cslot name=\"toc\" slot=\"toc\" /\u003e\n\u003c/DocsLayout\u003e\n```\n\n### 4. Add a page\n\nCreate `src/pages/index.mdx`:\n\n```\n---\ntitle: Welcome! # Used as the meta title and in the navigation sidebar\nlayout: 'src/layouts/DocsLayout.astro'\n---\n\n# Welcome\n\nUse standard Markdown to write documentation articles.\n\nOr use prebuilt components:\n\n\u003cYoutube id=\"dQw4w9WgXcQ\" /\u003e\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falephdata%2Fastro-theme-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falephdata%2Fastro-theme-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falephdata%2Fastro-theme-docs/lists"}