{"id":18561285,"url":"https://github.com/apostrophecms/gatsby-source-apostrophe","last_synced_at":"2025-05-15T16:34:10.865Z","repository":{"id":48677738,"uuid":"329996788","full_name":"apostrophecms/gatsby-source-apostrophe","owner":"apostrophecms","description":"Gatsby source plugin for ApostropheCMS","archived":false,"fork":false,"pushed_at":"2021-07-14T15:54:51.000Z","size":87,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-05-08T10:54:56.011Z","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":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/apostrophecms.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-15T18:53:35.000Z","updated_at":"2021-08-21T17:40:38.000Z","dependencies_parsed_at":"2022-08-29T05:31:42.027Z","dependency_job_id":null,"html_url":"https://github.com/apostrophecms/gatsby-source-apostrophe","commit_stats":null,"previous_names":[],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fgatsby-source-apostrophe","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fgatsby-source-apostrophe/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fgatsby-source-apostrophe/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/apostrophecms%2Fgatsby-source-apostrophe/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/apostrophecms","download_url":"https://codeload.github.com/apostrophecms/gatsby-source-apostrophe/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254377629,"owners_count":22061189,"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-11-06T22:06:25.216Z","updated_at":"2025-05-15T16:34:10.845Z","avatar_url":"https://github.com/apostrophecms.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gatsby-source-apostrophe\n\nSource plugin for accessing [ApostropheCMS 3.x content APIs](https://v3.docs.apostrophecms.org/reference/api/) in [Gatsby](https://www.gatsbyjs.com/docs/tutorial/)\n\n## Install\n\n`npm install gatsby-source-apostrophe`\n\n## How to use\n\n1. Review [Gatsby documentation on using source plugins](https://www.gatsbyjs.com/docs/tutorial/part-five/). 🤓\n2. [Add an API key to the Apostrophe app](https://v3.docs.apostrophecms.org/reference/api/authentication.html#api-keys) to include as the `apiKey` option.\n3. Enter the Apos app root domain as the `baseUrl` option. For local development this will likely be `http://localhost:3000`.\n4. Add an array of the piece types (custom content types) you want available to Gatsby in the `pieceTypes` array.\n\n```javascript\n// In your gatsby-config.js\nmodule.exports = {\n  plugins: [\n    {\n      resolve: `gatsby-source-apostrophe`,\n      options: {\n        apiKey: 'my-apos-api-key',\n        baseUrl: 'http://localhost:3000',\n        pieceTypes: [\n          '@apostrophecms/file',\n          'my-piece-type'\n        ]\n      }\n    }\n  ]\n}\n```\n\n## Options\n\n### apiKey (required)\n\nAn ApostropheCMS API key with permissions to make GET requests. [Read more about setting up API keys](https://v3.docs.apostrophecms.org/reference/api/authentication.html#api-keys) in the Apostrophe documentation.\n\n### baseUrl (required)\n\nThe base URL for API requests. Usually this will be the root domain of the Apostrophe website or application with no trailing slash. In local development it will be `http://localhost:3000` by default.\n\n### pieceTypes\n\nAn array of Apostrophe piece type names. These will the same as the key name entered in the `app.js` `modules` object in the Apostrophe app. You may include core piece types that are not included by default, e.g, `@apostrophecms/file`, `@apostrophecms/image-tag`.\n\n### renderPages\n\nDefaults to `true`. Set this to `false` to avoid an additional request for each Apostrophe page in order to add the page's rendered HTML to the `AposCorePage` nodes.\n\n## Notes\n\n### Naming\n\nApostrophe content node types in Gatsby's GraphQL API are all prefixed with `Apos`. So if you include your `article` piece type, it will appear in the GraphQL API as `AposArticle` nodes and the query collections will be `aposArticle` and `allAposArticle`.\n\nApostrophe core piece types and pages are prefixed `AposCore`. For example, including the core `@apostrophecms/file` piece type will create `AposCoreFile` nodes. Other scoped module names will be converted to pascal-case, removing punctuation, and prefixed with `Apos`. For example, `@skynet/bad-robots` and `@skynet/badRobots` will be converted to `AposSkynetBadRobots`.\n\n### Rendered content\n\nApostrophe \"pieces\" are well suited to being delivered as structured, JSON-like data. However, the power of Apostrophe really shines when editors build custom series of content widgets in \"areas.\" Because areas can contain many types of widgets, and thus are not consistent in data structure, it is usually more useful to retrieve those from the APIs as rendered HTML.\n\nArea fields on piece types will be available in the GraphQL queries with a `_rendered` property containing a string of rendered HTML. All other field types are delivered directly as their normal data types, e.g., strings, number, arrays, etc.\n\n#### Rendered pages\n\nApostrophe pages usually consist primarily of these content \"areas,\" populated with any number of different widget types. Unless you add `renderPages: false` to this source plugin's options, pages will appear with a `_rendered` property in Gatsby GraphQL queries. This property's value is a string of HTML, rendered using the relevant page template in the Apostrophe app. See [the page API documentation](https://v3.docs.apostrophecms.org/reference/api/pages.html#delete-api-v1-apostrophecms-page-id) for more specifics on what is rendered.\n\nThat HTML can be used in your Gatsby site to [programmatically create pages](https://www.gatsbyjs.com/docs/tutorial/part-seven/) using the right layout component and slug structure for your site.\n\nIf there are parts of the Apostrophe page templates that you do *not* want to include in the rendered response, you can wrap those in the following Nunjucks conditional (these requests include a `?headless=true` parameter):\n\n```django\n\u003c!-- For example, in the Apostrophe site's `views/layout.html` --\u003e\n{% if not data.query.headless == 'true' %}\n  \u003c!-- Template wrapper you don't want in rendered responses. --\u003e\n{% endif %}\n```\n\n## Planned features\n\n- A video player JS to support the Apostrophe core video widget in areas\n- Option for Apostrophe pages to automatically generate Gatsby pages\n- An option to make all piece types available in Gatsby GraphQL queries without naming them\n\n## License\n gatsby-source-apostrophe is released under the [MIT License](https://github.com/apostrophecms/gatsby-source-apostrophe/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapostrophecms%2Fgatsby-source-apostrophe","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fapostrophecms%2Fgatsby-source-apostrophe","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fapostrophecms%2Fgatsby-source-apostrophe/lists"}