{"id":13814536,"url":"https://github.com/GitbookIO/theme-api","last_synced_at":"2025-05-15T03:34:42.945Z","repository":{"id":73453685,"uuid":"59033648","full_name":"GitbookIO/theme-api","owner":"GitbookIO","description":"Theme for publishing a beautiful API documentation with GitBook","archived":false,"fork":false,"pushed_at":"2017-02-28T15:17:17.000Z","size":770,"stargazers_count":150,"open_issues_count":14,"forks_count":27,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-08T04:17:42.087Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/GitbookIO.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}},"created_at":"2016-05-17T15:15:14.000Z","updated_at":"2025-02-06T09:59:47.000Z","dependencies_parsed_at":"2023-02-25T10:00:26.193Z","dependency_job_id":null,"html_url":"https://github.com/GitbookIO/theme-api","commit_stats":{"total_commits":68,"total_committers":2,"mean_commits":34.0,"dds":"0.014705882352941124","last_synced_commit":"417ebe7ad0e58783855e27b734a428f5797fdf9a"},"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Ftheme-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Ftheme-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Ftheme-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/GitbookIO%2Ftheme-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/GitbookIO","download_url":"https://codeload.github.com/GitbookIO/theme-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254266521,"owners_count":22042123,"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":"2024-08-04T04:02:09.503Z","updated_at":"2025-05-15T03:34:42.239Z","avatar_url":"https://github.com/GitbookIO.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# GitBook API Theme\n\nTheme for using GitBook to publish an API documentation.\n\nThis theme works perfectly with search plugins (like [the default plugin](https://github.com/GitbookIO/plugin-search) or [algolia](https://github.com/GitbookIO/plugin-algolia)).\n\n![Screenshot](img/theme-api.png)\n\nIt also integrates well with the default fontsettings plugin to use the Dark theme.\n\n![Dark theme](img/theme-dark.png)\n\n### Usage\n\nThis theme requires GitBook version 3 or later.\n\nAdd the theme to your book's configuration (book.json):\n\n```json\n{\n    \"plugins\": [\"theme-api\"]\n}\n```\n\nTo use the Dark theme by default:\n\n```json\n{\n    \"plugins\": [\"theme-api\"],\n    \"pluginsConfig\": {\n        \"theme-api\": {\n            \"theme\": \"dark\"\n        }\n    }\n}\n```\n\n### Defining methods\n\nThe theme allows to easily define methods with examples for different languages, using the templating blocks syntax.\n\nA method block can contain any number of nested `sample` and `common` blocks.\n\nThose nested blocks are documented below.\n\n#### Sample blocks\n\nWhile the body of the method block will be used as the definition for your method, each `sample` will be used to display examples. To do so, each `sample` block should specify a language using the `lang` arguments.\n\nThis is great for managing examples in different languages, for instance when documenting multiple API clients.\n\n    {% method %}\n    ## Install {#install}\n\n    The first thing is to get the GitBook API client.\n\n    {% sample lang=\"js\" %}\n    ```bash\n    $ npm install gitbook-api\n    ```\n\n    {% sample lang=\"go\" %}\n    ```bash\n    $ go get github.com/GitbookIO/go-gitbook-api\n    ```\n    {% endmethod %}\n\n![JS Sample](img/sample-js.png)\n![Go sample](img/sample-go.png)\n\nOn each page containing `method` blocks with samples, a switcher is automatically added at the top-right corner to easily select which language to display.\n\nThe name of each language can be configured in your `book.json` file, with it's `lang` property corresponding to the `sample` block `lang` argument:\n\n```json\n{\n  \"plugins\": [\"theme-api\"],\n  \"pluginsConfig\": {\n    \"theme-api\": {\n      \"languages\": [\n        {\n          \"lang\": \"js\",          // sample lang argument\n          \"name\": \"JavaScript\",  // corresponding name to be displayed\n          \"default\": true        // default language to show\n        },\n        {\n          \"lang\": \"go\",\n          \"name\": \"Go\"\n        }\n      ]\n    }\n  }\n}\n```\n\n![Language switcher](img/lang-switcher.png)\n\nMost programming languages are supported by default, with name mapping following the [highlight.js convention](http://highlightjs.readthedocs.io/en/latest/css-classes-reference.html#language-names-and-aliases).\n\nNote that a `sample` block can contain any markdown content to be displayed for this language, not only code blocks, as illustrated below.\n\n\n#### Common blocks\n\nCommon blocks are used to display content to be displayed for all languages in your examples.\n\n    {% method %}\n    ## Simple method\n\n    {% sample lang=\"js\" %}\n    This text will only appear for JavaScript.\n\n    {% sample lang=\"go\" %}\n    This text will only appear for Go.\n\n    {% common %}\n    This will appear for both JavaScript and Go.\n    {% endmethod %}\n\n\n### Layout\n\nThe theme provides two layouts to display your examples: one-column or two-columns (split).\n\n###### One column layout\n![One column](img/one-column.png)\n\n###### Split layout\n![Split](img/split.png)\n\nThe layout can be toggled from the toolbar using the layout icon: ![Layout icon](img/layout-icon.png)\n\nThe default aspect can also be set in the theme configuration in the `book.json` file:\n\n```json\n{\n  \"plugins\": [\"theme-api\"],\n  \"pluginsConfig\": {\n    \"theme-api\": {\n      \"split\": true\n    }\n  }\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGitbookIO%2Ftheme-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FGitbookIO%2Ftheme-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FGitbookIO%2Ftheme-api/lists"}