{"_id":"5937b2388e8d9b002f1df27c","category":{"_id":"5937b2388e8d9b002f1df26f","version":"5937b2378e8d9b002f1df26e","project":"542fe92a5eceb608003fddc8","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2014-10-04T12:33:46.255Z","from_sync":false,"order":0,"slug":"documentation","title":"Documentation"},"project":"542fe92a5eceb608003fddc8","user":"542c5cfcddd3190e00228849","parentDoc":null,"version":{"_id":"5937b2378e8d9b002f1df26e","project":"542fe92a5eceb608003fddc8","__v":1,"createdAt":"2017-06-07T07:58:47.936Z","releaseDate":"2017-06-07T07:58:47.936Z","categories":["5937b2388e8d9b002f1df26f","5937b2388e8d9b002f1df270","5937b2388e8d9b002f1df271","5937b2388e8d9b002f1df272","5937b2388e8d9b002f1df273","5937b2388e8d9b002f1df274"],"is_deprecated":false,"is_hidden":false,"is_beta":true,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0.0"},"__v":0,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-10-06T12:30:37.167Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"A good reference for your package.json, is always the latest [Casper](https://github.com/TryGhost/Casper/blob/ghost-1.0/package.json)\n\n----\n\nGhost's package.json is heavily based upon the [npm package.json](https://docs.npmjs.com/files/package.json), and is fully compatible with npm. There is absolutely no requirement or expectation that your theme will be published to npm, however we recognise that it useful to utilise npm for managing theme dependencies.\n\nIf you're not sure about any aspect of this spec, you should refer back to the [npm package.json docs](https://docs.npmjs.com/files/package.json) for reference. \n\nSince Ghost 1.0 some `package.json` files are required. More will follow.\n\n## Required properties\n\n### `name`\n\nAll themes are required to have a package name. This tells us what you want your theme to be called, otherwise the only reference we have is the name of the zip file or folder that the theme is contained within, which is not controlled by the theme developer.\n\nA valid name is:\n- Lowercase\n- URL-safe (that means no spaces, use hyphens)\n- Doesn't start with a dot or underscore\n- A maximum of 214 chars long \n\nAn example of a valid name is `my-favourite-theme`.\n\nThis should be lowercase and hyphenated, E.g. `my-theme` not `My Theme`.\n\n**How Ghost will use this:**\n\nThe name of your theme will be used to list your theme. We may use a humanise function to display your package name, e.g. `my-theme` may be displayed as My Theme.\n\n### `version`\n\nIn order to manage updates, your theme is required to provide a semver-compliant version number.\n\nYou can find out more about semver on semver.org, or you can also install node-semver to check your version manually.\n\nA semver version MUST include 3 parts: major.minor.patch. \n\nTheme developers are expected to version their themes sensibly. The simplest rules are:\n- If the theme is available to be used, it should have at least reached version 1.0.0. \n- Change the 3rd patch number for bug fixes only\n- Change the 2nd minor number for feature additions\n- Change the 1st major number for breaking changes\n\n### `author`\n\nAuthor should be an Object and your `package.json` must contain an `author.email` property. `url` and `name` are optional.\n\n```\n\"author\": {\n    \"name\": \"Theme Author\",\n    \"email\": \"hello:::at:::example.com\",\n    \"url\": \"https://example.com\"\n}\n```\n-----\n## Recommended Property\n\n### `config.posts_per_page`\n\nWith Ghost 1.0 we removed the the \"Posts per page\" settings from the Ghost Admin and keep it to the current theme to control it. You can set it up in your `package.json` like this:\n\n```\n\"config\": {\n    \"posts_per_page\": 3\n}\n```\nIf Ghost doesn't find this key in your themes' `package.json` it'll fall back to its default of 5 posts per page.\n\n----\n## Optional Properties\n\n### `description`\n\nProvide a short description of your theme and what makes it unique. This should be text-only (no HTML or markdown) and limited to 300 characters.\n\n### `engines`\n\nUse `engines.ghost` to indicate what version of Ghost your theme is compatible with. This should be a valid semver version or version range that Ghost can use to understand if your theme can be installed.\n\nExample for a theme, which is build for Ghost 1.0:\n\n```    \n\"engines\": {\n    \"ghost\": \"^1.0.0\"\n}\n```\n\n### `license`\n\nA valid license string, as per npm package.json. We recommend `MIT` ๐Ÿ˜‰\n\n### `gpm`\n\nGPM should be an Object as well. It takes a `type` property which indicates the nature of its purpose. For now, this will only be \"theme\".\n\nThe second property `categories` is an Array that should list out at most 2 Ghost Marketplace categories for inclusion. Categories can be found [here](https://gist.github.com/ErisDS/d0674f57eaa087c9f92cbfc8e984d2d6) but are subject to change.\n\nHere's an example for a theme with \"Minimal\" and \"Personal Blogs\" categories:\n\n```\n\"gpm\": {\n    \"type\": \"theme\",\n    \"categories\": [\n        \"Minimal\",\n        \"Personal Blogs\"\n    ]\n}\n```\n\n### `screenshots`\n\n You can provide a relative path or absolute URL to both `desktop` & `mobile` screenshots, e. g.\n\n```\n\"screenshots\": {\n    \"desktop\": \"assets/screenshot-desktop.jpg\",\n    \"mobile\": \"assets/screenshot-mobile.jpg\"\n}\n```\n\n### `demo`\n\nYou can also provide a working demo page of your Ghost install which runs the current theme.\n\n### `homepage`\n\nThe homepage should be a valid URL (GitHub URL is ok).","excerpt":"Specifications for the package.json file","slug":"packagejson","type":"basic","title":"Package.json"}

Package.json

Specifications for the package.json file

A good reference for your package.json, is always the latest [Casper](https://github.com/TryGhost/Casper/blob/ghost-1.0/package.json) ---- Ghost's package.json is heavily based upon the [npm package.json](https://docs.npmjs.com/files/package.json), and is fully compatible with npm. There is absolutely no requirement or expectation that your theme will be published to npm, however we recognise that it useful to utilise npm for managing theme dependencies. If you're not sure about any aspect of this spec, you should refer back to the [npm package.json docs](https://docs.npmjs.com/files/package.json) for reference. Since Ghost 1.0 some `package.json` files are required. More will follow. ## Required properties ### `name` All themes are required to have a package name. This tells us what you want your theme to be called, otherwise the only reference we have is the name of the zip file or folder that the theme is contained within, which is not controlled by the theme developer. A valid name is: - Lowercase - URL-safe (that means no spaces, use hyphens) - Doesn't start with a dot or underscore - A maximum of 214 chars long An example of a valid name is `my-favourite-theme`. This should be lowercase and hyphenated, E.g. `my-theme` not `My Theme`. **How Ghost will use this:** The name of your theme will be used to list your theme. We may use a humanise function to display your package name, e.g. `my-theme` may be displayed as My Theme. ### `version` In order to manage updates, your theme is required to provide a semver-compliant version number. You can find out more about semver on semver.org, or you can also install node-semver to check your version manually. A semver version MUST include 3 parts: major.minor.patch. Theme developers are expected to version their themes sensibly. The simplest rules are: - If the theme is available to be used, it should have at least reached version 1.0.0. - Change the 3rd patch number for bug fixes only - Change the 2nd minor number for feature additions - Change the 1st major number for breaking changes ### `author` Author should be an Object and your `package.json` must contain an `author.email` property. `url` and `name` are optional. ``` "author": { "name": "Theme Author", "email": "[email protected]", "url": "https://example.com" } ``` ----- ## Recommended Property ### `config.posts_per_page` With Ghost 1.0 we removed the the "Posts per page" settings from the Ghost Admin and keep it to the current theme to control it. You can set it up in your `package.json` like this: ``` "config": { "posts_per_page": 3 } ``` If Ghost doesn't find this key in your themes' `package.json` it'll fall back to its default of 5 posts per page. ---- ## Optional Properties ### `description` Provide a short description of your theme and what makes it unique. This should be text-only (no HTML or markdown) and limited to 300 characters. ### `engines` Use `engines.ghost` to indicate what version of Ghost your theme is compatible with. This should be a valid semver version or version range that Ghost can use to understand if your theme can be installed. Example for a theme, which is build for Ghost 1.0: ``` "engines": { "ghost": "^1.0.0" } ``` ### `license` A valid license string, as per npm package.json. We recommend `MIT` ๐Ÿ˜‰ ### `gpm` GPM should be an Object as well. It takes a `type` property which indicates the nature of its purpose. For now, this will only be "theme". The second property `categories` is an Array that should list out at most 2 Ghost Marketplace categories for inclusion. Categories can be found [here](https://gist.github.com/ErisDS/d0674f57eaa087c9f92cbfc8e984d2d6) but are subject to change. Here's an example for a theme with "Minimal" and "Personal Blogs" categories: ``` "gpm": { "type": "theme", "categories": [ "Minimal", "Personal Blogs" ] } ``` ### `screenshots` You can provide a relative path or absolute URL to both `desktop` & `mobile` screenshots, e. g. ``` "screenshots": { "desktop": "assets/screenshot-desktop.jpg", "mobile": "assets/screenshot-mobile.jpg" } ``` ### `demo` You can also provide a working demo page of your Ghost install which runs the current theme. ### `homepage` The homepage should be a valid URL (GitHub URL is ok).