![\"\"](\"https://cdn.rawgit.com/rasshofer/cms/master/docs/files.png\")
\n\n(You can sort files by prepending those numbers, just like pages.)\n\n### Adding meta data to your files and images\n\nJust like page content files, you may also create file content files, containing stuff like titles or captions. Simply add a text file for each file matching the full name of the file, followed by your content file extension (i.e. `test.jpg.md` for the file `test.jpg`). Inside those text files you can define your own fields and content, just like regular content files.\n\n```md\nTitle: Very nice image\n----\nCaption: This is a very nice image with loads of colors and stuff.\n```\n\n(`cms` will automatically fetch this data from the matching text files and add them to your file object, which you can access in the templates later.)\n\n### Anatomy of a page object\n\nThe following object dump represents the properties that are passed into the template engine next to globals and addons for every page.\n\n```js\nPage {\n file: '/Users/johndoe/Repositories/my-fancy-website/content/home.md',\n parent: undefined,\n genesis: Page,\n index: 0,\n visible: false,\n invisible: true,\n identifier: '',\n url: '/',\n output: '/Users/johndoe/Repositories/my-fancy-website/build/index.html',\n template: 'home',\n children: [\n Page,\n Page,\n …\n ],\n hasChildren: true,\n files: [\n File,\n File,\n …\n ],\n hasFiles: true,\n images: [\n Image,\n Image,\n …\n ],\n hasImages: true,\n videos: [\n File,\n File,\n …\n ],\n hasVideos: true,\n sounds: [\n File,\n File,\n …\n ],\n hasSounds: true,\n documents: [\n File,\n File,\n …\n ],\n hasDocuments: true,\n title: 'Lorem ipsum dolor sit amet',\n text: 'Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet. Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.'\n}\n```\n\n`parent` may include a reference to the current page’s parent page. This may be useful for stuff like breadcrumb navigations. In case the page is a first level page, `parent` is simply `undefined`.\n\n`genesis` may include a reference to the root page. This may be useful for stuff like navigations (i.e. show all first level pages). In case the page is the first level page itself, `genesis` is simply a reference to `this` (= the page instance itself).\n\n`children` may contain any direct child pages of the current page. This may be useful for stuff like navigations. In case the page has no children, `children` will be an empty array.\n\n`images`, `videos`, `sounds`, and `documents` may contain any matching files of the current page. `files` contains all files combined. In case the page does not contain any files, these properties will be empty arrays.\n\n`title` and `text` are exemplary custom properties taken from the content file.\n\n## Virtual pages\n\nUsing virtual pages, you can combine the file-based architecture with content from any other data source like APIs or databases. Any page that doesn’t exist in the content folder is called a »virtual page«. You can add virtual pages to any existing page (even the genesis page) using the `addVirtualPage` method which accepts `properties` containing all necessarry page properties.\n\n### Properties\n\nThe following properties are expected by the system and can be extended using any amount of custom properties (e.g. `title`, `text`, …).\n\n#### `index` (Default: `0`)\n\nWhile number prefixes in front of folder names are used for ordering/sorting pages and defining their visibility for file-based pages, you may want to define the index explicitly for virtual pages.\n\n#### `identifier` (required)\n\nWhile the nested folder names of its text file determine the identifier of a page (and hence its URL), you have to define the full identifier explicitly for virtual pages.\n\n#### `template` (required)\n\nWhile the name of its text file determines which template is used by the system for file-based pages, you have to define the template name explicitly for virtual pages.\n\n### Example\n\n```js\nconst instance = cms({\n …\n});\nconst genesis = instance.get();\nconst projects = genesis.findPageByUrl('/projects');\n\nconst virtualProject = projects.addVirtualPage({\n identifier: 'projects/a',\n template: 'project',\n title: 'This is a virtual project',\n text: 'Lorem ipsum',\n});\n\nconst somethingElse = virtualProject.addVirtualPage({\n identifier: 'projects/a/a',\n template: 'project',\n title: 'This is a virtual project within another virtual project',\n someWeirdFieldName: 'Test'\n});\n```\n\n## Helpers\n\n### `basepath(url)`\n\nCallback function which prepends the `base` option (see below) to the specified `url`. This may be useful if you’re planning to run your static site within a sub directory.\n\nExample:\n\n```html\n\" rel=\"stylesheet\">\n```\n\n### `has(key)`\n\nReturns a boolean indicating whether the current page has the specified property. This may be useful if you’re working with dynamic page properties.\n\nExample:\n\n```ejs\n<% if (has('description')) { %>\n<%= description %>
\n<% } %>\n```\n\n### `get(key, defaultValue)`\n\nReturns the specified property (or the specified default value if it does not exist) for the current page. This may be useful if you’re working with dynamic page properties.\n\nExample:\n\n```ejs\n<% ['title', 'description'].forEach((prop) => { %>\n<%= get(prop, 'Something') %>
\n<% }) %>\n```\n\n### `findPageByUrl(url, context)`\n\nSearches the page tree (starting at `context`, which equals the `genesis` page by default) recursively for the the page that has the URL `url`. This may be useful if you need to use properties of other pages located somewhere else in the page tree.\n\nExample:\n\n```ejs\n<% const contactPage = findPageByUrl('/contact') %>\n\"><%= contactPage.title %>\n```\n\n## Shortcodes\n\nShortcodes let you do nifty things with very little effort by allowing you to create macros to be used in your page contents. A trivial shortcode example may look like this.\n\n```plain\n(youtube: jNQXAC9IVRw width: 480 height: 360)\n```\n\nThe example above shows a basic shortcode to embed a YouTube video. The actual embedment is done by an appropiate handler, called everytime the shortcode is used.\n\n```js\n{\n youtube: (attrs) => {\n return ``;\n }\n}\n```\n\nIn addition, the page object of the current page (which includes/invokes the shortcode) gets passed into the shortcode handler function as its (optional) second parameter. This allows shortcodes to interact with the page context.\n\n```js\n{\n photo: (attrs, page) => {\n const photo = page.images.find((item) => item.identifier === attrs.photo);\n\n if (photo) {\n return `\n