[ { "objectID": "documentation/quick-start#prerequisites", "page": "Quick Start", "title": "Prerequisites", "description": "", "content": "PHP 8.2+\nTerminal (a basic understanding of terminal)\nText editor, like VS Code and\/or Typora", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/quick-start/#prerequisites", "experimental": "0" }, { "objectID": "documentation/quick-start#1-download-cecil", "page": "Quick Start", "title": "1. Download Cecil", "description": "Download cecil.phar from your terminal:", "content": "Download cecil.phar from your terminal:\ncurl -LO https:\/\/cecil.app\/cecil.phar\nYou can also download Cecil manually, or use:\n\nHomebrew: brew install cecilapp\/tap\/cecil\nScoop: scoop install https:\/\/cecil.app\/scoop\/cecil.json", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/quick-start/#1-download-cecil", "experimental": "0" }, { "objectID": "documentation/quick-start#2-create-a-new-site", "page": "Quick Start", "title": "2. Create a new site", "description": "Create a directory for the website (e.g.: <mywebsite>), put cecil.phar in it, then run the new:site command:", "content": "Create a directory for the website (e.g.: <mywebsite>), put cecil.phar in it, then run the new:site command:\nphp cecil.phar new:site", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/quick-start/#2-create-a-new-site", "experimental": "0" }, { "objectID": "documentation/quick-start#3-add-a-page", "page": "Quick Start", "title": "3. Add a page", "description": "Run the new:page command:", "content": "Run the new:page command:\nphp cecil.phar new:page\nNow you can edit the newly created page with your Markdown editor: <mywebsite>\/pages\/<new-page>.md.\nWe recommend you to use Typora to edit your Markdown files.", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/quick-start/#3-add-a-page", "experimental": "0" }, { "objectID": "documentation/quick-start#4-check-the-preview", "page": "Quick Start", "title": "4. Check the preview", "description": "Run the following command to create a preview of the website:", "content": "Run the following command to create a preview of the website:\nphp cecil.phar serve\nThen navigate to http:\/\/localhost:8000.\nThe serve command runs a local HTTP server and a watcher: if a file (a page, a template or the config) is modified, the browser\u2019s current page is automatically reloaded.", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/quick-start/#4-check-the-preview", "experimental": "0" }, { "objectID": "documentation/quick-start#5-build-and-deploy", "page": "Quick Start", "title": "5. Build and deploy", "description": "When you are satisfied with the result, you can generate the website in order to deploy it on the Web.", "content": "When you are satisfied with the result, you can generate the website in order to deploy it on the Web.\nRun the following command to build the website:\nphp cecil.phar build\nYou can now copy the content of the _site directory to a Web server \ud83c\udf89\n\nCreate a blog\nIf you want to create a no-hassle blog, quickly, the starter blog is for you.\n\n\n\n\n\nThe easiest way to deploy and manage your blog is certainly with Netlify or Vercel.", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/quick-start/#5-build-and-deploy", "experimental": "0" }, { "objectID": "documentation/quick-start#deploy-to-netlify", "page": "Quick Start", "title": "Deploy to Netlify", "description": "", "content": "", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/quick-start/#deploy-to-netlify", "experimental": "0" }, { "objectID": "documentation/quick-start#deploy-to-vercel", "page": "Quick Start", "title": "Deploy to Vercel", "description": "", "content": "", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/quick-start/#deploy-to-vercel", "experimental": "0" }, { "objectID": "documentation/content#file-system-tree", "page": "Content", "title": "File system tree", "description": "Project files organization.", "content": "Project files organization.\n<mywebsite>\n\u251c\u2500 pages\n| \u251c\u2500 blog <- Section\n| | \u251c\u2500 post-1.md <- Page in Section\n| | \u2514\u2500 post-2.md\n| \u251c\u2500 projects\n| | \u2514\u2500 project-a.md\n| \u2514\u2500 about.md <- Root page\n\u251c\u2500 assets\n| \u251c\u2500 styles.scss <- Asset file\n| \u2514\u2500 logo.png\n\u251c\u2500 static\n| \u2514\u2500 file.pdf <- Static file\n\u2514\u2500 data\n \u2514\u2500 authors.yml <- Data collection", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#file-system-tree", "experimental": "0" }, { "objectID": "documentation/content#built-website-tree", "page": "Content", "title": "Built website tree", "description": "Result of the build.", "content": "Result of the build.\n<mywebsite>\n\u2514\u2500 _site\n \u251c\u2500 index.html <- Generated home page\n \u251c\u2500 blog\/\n | \u251c\u2500 index.html <- Generated list of posts\n | \u251c\u2500 post-1\/index.html <- A blog post\n | \u2514\u2500 post-2\/index.html\n \u251c\u2500 projects\/\n | \u251c\u2500 index.html\n | \u2514\u2500 project-a\/index.html\n \u251c\u2500 about\/index.html\n \u251c\u2500 styles.css\n \u251c\u2500 logo.png\n \u2514\u2500 file.pdf\nBy default each page is generated as slugified-filename\/index.html to get a \u201cbeautiful\u201c URL like https:\/\/mywebsite.tld\/section\/slugified-filename\/.\nTo get an \u201cugly\u201d URL (like 404.html instead of 404\/), set uglyurl: true in page front matter.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#built-website-tree", "experimental": "0" }, { "objectID": "documentation/content#file-based-routing", "page": "Content", "title": "File based routing", "description": "Markdown files in the pages directory enable file based routing. Meaning that adding a pages\/my-projects\/project-a.md for instance will make it available at \/project-a in your browser.", "content": "Markdown files in the pages directory enable file based routing. Meaning that adding a pages\/my-projects\/project-a.md for instance will make it available at \/project-a in your browser.\nFile:\n pages\/my-projects\/project-a.md\n \u2514\u2500\u2500\u2500\u2500\u2500 filepath \u2500\u2500\u2500\u2500\u2500\u2500\u2518\nURL:\n \u250c\u2500\u2500\u2500\u2500\u2500 baseurl \u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500 path \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n https:\/\/example.com\/my-projects\/project-a\/index.html\n \u2514\u2500 section \u2500\u2534\u2500 slug \u2500\u2500\u2518\nTwo kinds of prefixes can alter the URL. See the File prefix section below.\nPages\nA page is a file made up of a front matter and a body.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#file-based-routing", "experimental": "0" }, { "objectID": "documentation/content#front-matter", "page": "Content", "title": "Front matter", "description": "The front matter is a collection of variables (in key\/value format) surrounded by ---.", "content": "The front matter is a collection of variables (in key\/value format) surrounded by ---.\nExample:\n---\ntitle: \"The title\"\ndate: 2019-02-21\ntags: [tag 1, tag 2]\ncustomvar: \"Value of customvar\"\n---\nYou can also use <!-- --> or +++ as separator.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#front-matter", "experimental": "0" }, { "objectID": "documentation/content#body", "page": "Content", "title": "Body", "description": "Body is the main content of a page, it could be written in Markdown or in plain text.", "content": "Body is the main content of a page, it could be written in Markdown or in plain text.\nExample:\n# Header\n\n[toc]\n\n## Sub-Header 1\n\nLorem ipsum dolor [sit amet](https:\/\/example.com), consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.\n<!-- excerpt -->\nUt enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\n\n## Sub-Header 2\n\n![Description](\/image.jpg \"Title\")\n\n## Sub-Header 3\n\n:::tip\nThis is advice.\n:::\nMarkdown\nCecil supports Markdown format, but also Markdown Extra.\nCecil also provides extra features to enhance your content, see below.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#body", "experimental": "0" }, { "objectID": "documentation/content#attributes", "page": "Content", "title": "Attributes", "description": "With Markdown Extra you can set an id, class and custom attributes on certain elements using an attribute block.\nFor instance, put the desired attribute(s) after a header, a fenced code block, a link or an image at the end of the line inside curly brackets, like this:", "content": "With Markdown Extra you can set an id, class and custom attributes on certain elements using an attribute block.\nFor instance, put the desired attribute(s) after a header, a fenced code block, a link or an image at the end of the line inside curly brackets, like this:\n## Header {#id .class attribute=value}\nFor an inline element, like a link, you must use a line break after the closing brace:\nLorem ipsum [dolor](url){attribute=value} \nsit amet.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#attributes", "experimental": "0" }, { "objectID": "documentation/content#links", "page": "Content", "title": "Links", "description": "You can create a link with the syntax [Text](url), where url can be a path, a relative path to a Markdown file, an external URL, etc.", "content": "You can create a link with the syntax [Text](url), where url can be a path, a relative path to a Markdown file, an external URL, etc.\nExample:\n[Link to a path](\/about\/)\n[Link to a Markdown file](..\/about.md)\n[Link to Cecil website](https:\/\/cecil.app)\nLink to a page\nYou can easily create a link to a page with the syntax [Page title](page:page-id).\nExample:\n[Link to a blog post](page:blog\/post-1)\nExternal\nBy default external links have the following value for rel attribute: noopener noreferrer.\nExample:\n<a href=\"<url>\" rel=\"noopener noreferrer\">Link to another website<\/a>\nYou can change this behavior with pages.body.links.external options.\nEmbedded links\nCecil can try to turn a link into embedded content by using the {embed} attribute or by setting the global configuration option pages.body.links.embed.enabled to true.\nOnly YouTube, Vimeo, Dailymotion, and GitHub Gists links are supported.\nExample:\n[CECIL : LE g\u00e9n\u00e9rateur de SITES STATIQUES en PHP](https:\/\/www.youtube.com\/watch?v=ur8koU0iYvc){embed}\n\n\n\nLocal video\/audio files\nCecil can also create a video and audio HTML elements, through the file extension.\nExample:\n[Video file](video.mp4){embed controls poster=\/images\/video-test.png}\n[Audio file](song.mp3){embed controls}\nIs converted to:\n<video src=\"\/video.mp4\" controls poster=\"\/images\/video-test.png\" style=\"max-width:100%;height:auto;\"><\/video>\n<audio src=\"\/song.mp3\" controls><\/audio>", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#links", "experimental": "0" }, { "objectID": "documentation/content#images", "page": "Content", "title": "Images", "description": "To add an image, use an exclamation mark (!) followed by alternative description in brackets ([]), and the path or URL to the image in parentheses (()).\nYou can optionally add a title in quotation marks.", "content": "To add an image, use an exclamation mark (!) followed by alternative description in brackets ([]), and the path or URL to the image in parentheses (()).\nYou can optionally add a title in quotation marks.\n![Alternative description](\/image.jpg \"Image title\")\nThe path should be relative to the root of your website (e.g.: \/image.jpg), however Cecil is able to normalize a path relative to assets and static directories (e.g.: ..\/..\/assets\/image.jpg).\nLazy loading\nCecil adds the attribute loading=\"lazy\" to each image.\nExample:\n![](\/image.jpg)\nIs converted to:\n<img src=\"\/image.jpg\" loading=\"lazy\">\nYou can disable this behavior with the attribute {loading=eager} or with the lazy option.\nDecoding\nCecil adds the attribute decoding=\"async\" to each image.\nExample:\n![](\/image.jpg)\nIs converted to:\n<img src=\"\/image.jpg\" decoding=\"async\">\nYou can disable this behavior with the attribute {decoding=auto} or with the decoding option.\nResize\nEach image in the body can be resized automatically by setting a smaller width than the original one, with the extra attribute {width=X}.\nExample:\n![](\/image.jpg){width=800}\nIs converted to:\n<img src=\"\/thumbnails\/800\/image.jpg\" width=\"800\" height=\"600\">\nRatio is preserved (height attribute is calculated automatically), the original file is not altered and the resized version is stored in \/thumbnails\/<width>\/.\nThis feature requires GD. Imagick and libvips can also be used as optional backends when available; otherwise it only adds a width HTML attribute to the img tag.\nFormats\nIf the formats option is defined, alternatives images are created and added.\nExample:\n![](\/image.jpg)\nCould be converted to:\n<picture>\n <source srcset=\"\/image.avif\" type=\"image\/avif\">\n <source srcset=\"\/image.webp\" type=\"image\/webp\">\n <img src=\"\/image.jpg\">\n<\/picture>\nPlease note that not all image formats are always included in the PHP image extensions.\nResponsive\nIf the responsive option is enabled, then all images in the body will be made responsive automatically.\nExample:\n![](\/image.jpg){width=800}\nwill be converted to:\n<img src=\"\/thumbnails\/800\/image.jpg\" width=\"800\" height=\"600\"\n srcset=\"\/thumbnails\/320\/image.jpg 320w,\n \/thumbnails\/640\/image.jpg 640w,\n \/thumbnails\/800\/image.jpg 800w\"\n sizes=\"100vw\"\n>\nBecause a body image is converted into an Asset, the different widths must be defined in assets configuration.\nThe sizes attribute takes the value of the assets.images.responsive.sizes.default configuration option, but it can be changed by creating a new entry named after a class added to the image.\nExample:\nassets:\n images:\n responsive:\n sizes:\n default: 100vw\n my_class: \"(max-width: 800px) 768px, 1024px\"\n![](\/image.jpg){.my_class}\nYou can combine formats and responsive options.\nCSS class\nYou can set a default value to the class attribute of each image with the class option.\nCaption\nThe optional title can be used to create a caption (figcaption) automatically by enabling the caption option.\nExample:\n![](\/images\/img.jpg \"Title\")\nIs converted to:\n<figure>\n <img src=\"\/image.jpg\" title=\"Title\">\n <figcaption>Title<\/figcaption>\n<\/figure>\nCaption supports Markdown content.\nLocalized image\nFor translated pages, Cecil first looks for a language-suffixed file when resolving Markdown image paths.\nExample:\n![](\/images\/cecil-logo.png)\nWith a French page (fr), Cecil tries \/images\/cecil-logo.fr.png first, then falls back to \/images\/cecil-logo.png.\nPlaceholder\nAs images are typically heavier and slower resources, and they don\u2019t block rendering, we should attempt to give users something to look at while they wait for the image to arrive.\nThe placeholder attribute accepts two options:\n\ncolor: display a colored background (based on image dominant color)\nlqip: Low-Quality Image Placeholder\n\nExamples:\n![](\/images\/img.jpg){placeholder=color}\n![](\/images\/img.jpg){placeholder=lqip}\nYou can set a value to the placeholder attribute for each image with the placeholder option.\nThe lqip option is not compatible with animated GIF.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#images", "experimental": "0" }, { "objectID": "documentation/content#table-of-contents", "page": "Content", "title": "Table of contents", "description": "You can add a table of contents with the following Markdown syntax:", "content": "You can add a table of contents with the following Markdown syntax:\n[toc]\nBy default, the ToC extracts H2 and H3 headings. You can change this behavior with body options.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#table-of-contents", "experimental": "0" }, { "objectID": "documentation/content#excerpt", "page": "Content", "title": "Excerpt", "description": "An excerpt can be defined in the body with one of those following tags: excerpt or break.", "content": "An excerpt can be defined in the body with one of those following tags: excerpt or break.\nExample:\nIntroduction.\n<!-- excerpt -->\nMain content.\nThen use the excerpt_html filter in your template.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#excerpt", "experimental": "0" }, { "objectID": "documentation/content#notes", "page": "Content", "title": "Notes", "description": "Create a Note block (info, tips, important, etc.).", "content": "Create a Note block (info, tips, important, etc.).\nExample:\n:::tip\n**Tip:** This is advice.\n:::\nIs converted to:\n<aside class=\"note note-tip\">\n <p>\n <strong>Tip:<\/strong> This is advice.\n <\/p>\n<\/aside>\nTip: This is advice.\nOthers examples:\nempty\ninfo\ntip\nimportant\nwarning\ncaution", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#notes", "experimental": "0" }, { "objectID": "documentation/content#syntax-highlight", "page": "Content", "title": "Syntax highlight", "description": "Enables code block syntax highlighter by setting the pages.body.highlight.enabled option to true.", "content": "Enables code block syntax highlighter by setting the pages.body.highlight.enabled option to true.\nExample:\n\n```php\necho \"Hello world\";\n```\n\nIs rendered to:\necho \"Hello world\";\nYou must add the StyleSheet in the head of your template.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#syntax-highlight", "experimental": "0" }, { "objectID": "documentation/content#inserted-text", "page": "Content", "title": "Inserted text", "description": "Represents a range of text that has been added.", "content": "Represents a range of text that has been added.\n++text++\nIs converted to:\n<ins>text<\/ins>\nVariables\nThe front matter can contains custom variables applied to the current page.\nIt must be the first thing in the file and must be a valid YAML.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#inserted-text", "experimental": "0" }, { "objectID": "documentation/content#predefined-variables", "page": "Content", "title": "Predefined variables", "description": "", "content": "Variable\nDescription\nDefault value\nExample\n\n\n\n\ntitle\nTitle\nFile name without extension.\nPost 1\n\n\nlayout\nTemplate\nSee Lookup rules.\n404\n\n\ndate\nCreation date\nFile creation date (PHP DateTime object).\n2019\/04\/15\n\n\nsection\nSection\nPage's Section.\nblog\n\n\npath\nPath\nPage's path.\nblog\/post-1\n\n\nslug\nSlug\nPage's slug.\npost-1\n\n\npublished\nPublished or not\ntrue.\nfalse\n\n\ndraft\nPublished or not\nfalse.\ntrue\n\n\n\nAll the predefined variables can be overridden except section.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#predefined-variables", "experimental": "0" }, { "objectID": "documentation/content#updated", "page": "Content", "title": "updated", "description": "The updated variable is used to define the last modification date of a page.", "content": "The updated variable is used to define the last modification date of a page.\nExample:\n---\nupdated: 2026-02-02\n---\nBefore version 8.80.1, the updated variable was a predefined variable. It is now an optional variable (and must be defined in the front matter to be used).", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#updated", "experimental": "0" }, { "objectID": "documentation/content#menu", "page": "Content", "title": "menu", "description": "A page can be added to a menu.", "content": "A page can be added to a menu.\nThe entry name is the page title and the URL is the page path.\nThe same page can be added to multiple menus, and each entry's position can be set with the weight key (lowest first). The name key can be used to override the default entry name per menu.\nExamples:\n---\nmenu: main\n---\n---\nmenu: [main, navigation] # same page in multiple menus\n---\n---\nmenu:\n main:\n weight: 10\n navigation:\n weight: 20\n---\n---\ntitle: 'Our Expertise'\nmenu:\n main:\n weight: 15\n footer:\n weight: 15\n name: \"Expertise\" # override the entry name in this menu\n---", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#menu", "experimental": "0" }, { "objectID": "documentation/content#taxonomy", "page": "Content", "title": "Taxonomy", "description": "Taxonomy allows you to connect, relate and classify your website\u2019s content.\nIn Cecil, these terms are gathered within vocabularies.", "content": "Taxonomy allows you to connect, relate and classify your website\u2019s content.\nIn Cecil, these terms are gathered within vocabularies.\nVocabularies are declared in the Configuration.\n\nVocabulary\nA categorization of content (e.g.: tags, categories, etc.).\nTerm\nA term is an item of a vocabulary (e.g.: Development, PHP, etc.).\n\nExample:\n---\ntags: [\"Development\", \"PHP\"]\n---", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#taxonomy", "experimental": "0" }, { "objectID": "documentation/content#schedule", "page": "Content", "title": "Schedule", "description": "Schedules pages\u2019 publication.", "content": "Schedules pages\u2019 publication.\nExample:\nThe page will be published if current date is >= 2023-02-07:\nschedule:\n publish: 2023-02-07\nThis page is published if current date is <= 2022-04-28:\nschedule:\n expiry: 2022-04-28", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#schedule", "experimental": "0" }, { "objectID": "documentation/content#redirect", "page": "Content", "title": "redirect", "description": "As indicated by its name, the redirect variable is used to redirect a page to a dedicated URL.", "content": "As indicated by its name, the redirect variable is used to redirect a page to a dedicated URL.\nExample:\n---\nredirect: \"https:\/\/arnaudligny.fr\"\n---\nRedirect works with the redirect.html.twig template.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#redirect", "experimental": "0" }, { "objectID": "documentation/content#alias", "page": "Content", "title": "alias", "description": "Alias is a redirection to the current page", "content": "Alias is a redirection to the current page\nExample:\n---\ntitle: \"About\"\nalias:\n - contact\n---\nIn the previous example contact\/ redirects to about\/.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#alias", "experimental": "0" }, { "objectID": "documentation/content#output", "page": "Content", "title": "output", "description": "Defines the output format of the page.", "content": "Defines the output format of the page.\nAvailable formats are: html, atom, rss, json, xml, etc.\nYou can define one or more formats in an array.\nI\u2019s not required to define an output format, but if you do, it must be one of the available formats defined in the Configuration.\nExample:\n---\noutput: [html, atom]\n---", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#output", "experimental": "0" }, { "objectID": "documentation/content#external", "page": "Content", "title": "external", "description": "A page with an external variable try to fetch the content of the pointed resource.", "content": "A page with an external variable try to fetch the content of the pointed resource.\nExample:\n---\nexternal: \"https:\/\/raw.githubusercontent.com\/Cecilapp\/Cecil\/master\/README.md\"\n---", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#external", "experimental": "0" }, { "objectID": "documentation/content#file-prefix", "page": "Content", "title": "File prefix", "description": "The filename can contain a prefix to define date or weight variables of the page (used by sortby).", "content": "The filename can contain a prefix to define date or weight variables of the page (used by sortby).\nDefault prefix separators: _ and -.\nYou can customize them with the pages.prefix.separator option.\ndate\nThe date prefix is used to set the date of the page, and must be a valid date format (i.e.: \u00ab YYYY-MM-DD \u00bb).\nExample:\nIn \u00ab 2019-04-23_My blog post.md \u00bb:\n\nthe prefix is \u00ab 2019-04-23 \u00bb\nthe date of the page is \u00ab 2019-04-23 \u00bb\nthe title of the page is \u00ab My blog post \u00bb\n\nweight\nThe weight prefix is used to set the sort order of the page, and must be a valid integer value.\nExample:\nIn \u00ab 1_The first project.md \u00bb:\n\nthe prefix is \u00ab 1 \u00bb\nthe weight of the page is \u00ab 1 \u00bb\nthe title of the page is \u00ab The first project \u00bb", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#file-prefix", "experimental": "0" }, { "objectID": "documentation/content#section", "page": "Content", "title": "Section", "description": "Some dedicated variables can be used in a custom Section (i.e.: <section>\/index.md).", "content": "Some dedicated variables can be used in a custom Section (i.e.: <section>\/index.md).\nsortby\nThe order of pages in a Section can be changed.\nAvailable values are:\n\ndate: more recent first\ntitle: alphabetic order\nweight: lightest first\n\nExample:\n---\nsortby: title\n---\nMore options:\n---\nsortby:\n variable: date # \"date\", \"updated\", \"title\" or \"weight\"\n desc_title: false # used with \"date\" or \"updated\" variable value to sort by desc title order if items have the same date\n reverse: false # reversed if true\n---\npagination\nThe global pagination configuration is used by default, but you can change it for a specific Section.\nExample:\n---\npagination:\n max: 5\n path: \"page\"\n pagination: false\n---\ncascade\nAny variables in cascade are added to the front matter of all sub pages.\nExample:\n---\ncascade:\n banner: image.jpg\n---\nExisting variables are not overridden.\ncircular\nSet circular to true to enable circular navigation with page.<prev\/next>.\nExample:\n---\ncircular: true\n---", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#section", "experimental": "0" }, { "objectID": "documentation/content#home-page", "page": "Content", "title": "Home page", "description": "Like another section, Home page support sortby and pagination configuration.", "content": "Like another section, Home page support sortby and pagination configuration.\npagesfrom\nSet a valid Section name in pagesfrom to use pages collection from this Section in Home page.\nExample:\n---\npagesfrom: blog\n---", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#home-page", "experimental": "0" }, { "objectID": "documentation/content#excluded", "page": "Content", "title": "excluded", "description": "Set excluded to true to hide a page from list pages (i.e.: Home page, Section, Sitemap, etc.).", "content": "Set excluded to true to hide a page from list pages (i.e.: Home page, Section, Sitemap, etc.).\nExample:\n---\nexcluded: true\n---\nexcluded is different from published: an excluded page is published but hidden from list pages.\nSince version 8.49.0, the previous exclude variable have been changed to excluded.\nMultilingual\nIf your pages are available in multiple languages there is 2 different ways to define it:", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#excluded", "experimental": "0" }, { "objectID": "documentation/content#through-file-name", "page": "Content", "title": "Through file name", "description": "This is the common way to translate a page from the main language to another language.", "content": "This is the common way to translate a page from the main language to another language.\nYou just need to duplicate the reference page and suffix it with the target language code (e.g.: fr).\nExample:\n\u251c\u2500 about.md # the reference page\n\u2514\u2500 about.fr.md # the french version (`fr`)\nYou can change the URL of the translated page with the slug variable in the front matter. For example:\n---\nslug: a-propos\n---\n# about.md -> \/about\/\n# about.fr.md -> \/fr\/a-propos\/", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#through-file-name", "experimental": "0" }, { "objectID": "documentation/content#through-front-matter", "page": "Content", "title": "Through front matter", "description": "If you want to create a page in a language other than the main language, without it being a translation of an existing page, you can use the language variable in its front matter.", "content": "If you want to create a page in a language other than the main language, without it being a translation of an existing page, you can use the language variable in its front matter.\nExample:\n---\nlanguage: fr\n---", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#through-front-matter", "experimental": "0" }, { "objectID": "documentation/content#link-translated-pages", "page": "Content", "title": "Link translated pages", "description": "Each translated page reference the pages in others languages.", "content": "Each translated page reference the pages in others languages.\nThose pages collection is available in templates with the following variable:\n{{ page.translations }}\nThe langref variable is provided by default, but you can change it in the front matter:\n---\nlangref: my-page-ref\n---\nDynamic content\nWith this experimental feature you can use variables and shortcodes in the body.\nTo do this you must include a specific template:\n{{ include(page.content_template) }}\n(instead of {{ page.content }})", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#link-translated-pages", "experimental": "0" }, { "objectID": "documentation/content#display-variables", "page": "Content", "title": "Display variables", "description": "Front matter variables can be use in the body with the template\u2019s syntax {{ page.variable }}.", "content": "Front matter variables can be use in the body with the template\u2019s syntax {{ page.variable }}.\nExample:\n--\nvar: 'value'\n---\nThe value of `var` is {{ page.var }}.\n\nExperimental", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#display-variables", "experimental": "1" }, { "objectID": "documentation/content#shortcodes", "page": "Content", "title": "Shortcodes", "description": "Shortcodes are helpers to create dynamic content.", "content": "Shortcodes are helpers to create dynamic content.\n\nExperimental\n\nBuilt-in shortcodes\n2 shortcodes are available by default:\nYouTube\n{{ shortcode.youtube(id) }}\n\nid: YouTube video ID\n\nExample:\n{{ shortcode.youtube('NaB8JBfE7DY') }}\nGitHub Gist\n{{ shortcode.gist(user, id) }}\n\nuser: GitHub user name\nid: Gist ID\n\nExample:\n{{ shortcode.gist('ArnaudLigny', 'fbe791e05b93951ffc1f6abda8ee88f0') }}\nCustom shortcode\nA shortcode is a Twig macro you must add in a template named shortcodes.twig.\nExample:\nshortcodes.twig:\n{% extends 'extended\/macros.twig' %}\n\n{% block macros %}\n\n{# the \"foo\" shortcode #}\n{% macro foo(bar = 'bar') %}\n<strong>{{ bar }}<\/strong>\n{% endmacro %}\n\n{% endblock %}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/content/#shortcodes", "experimental": "1" }, { "objectID": "documentation/templates#kinds-of-templates", "page": "Templates", "title": "Kinds of templates", "description": "There are three kinds of templates: layouts, components, and other templates. Layouts are used to render pages, and each layout can include templates and components.", "content": "There are three kinds of templates: layouts, components, and other templates. Layouts are used to render pages, and each layout can include templates and components.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#kinds-of-templates", "experimental": "0" }, { "objectID": "documentation/templates#naming-convention", "page": "Templates", "title": "Naming convention", "description": "Template files are stored in the layouts\/ directory and must be named according to the following convention:", "content": "Template files are stored in the layouts\/ directory and must be named according to the following convention:\nlayouts\/(<section>\/)<type>|<layout>.<format>(.<language>).twig\n\n<section> (optional)\nThe section of the page (e.g.: blog).\n<type>\nThe page type: home (or index) for homepage, list for list, page for page, etc. (See Lookup rules for details).\n<layout> (optional)\nThe custom layout name defined in the front matter of the page (e.g.: layout: my-layout).\n<format>\nThe output format of the rendered page (e.g.: html, rss, json, xml, etc.).\n<language> (optional)\nThe language of the page (e.g.: fr).\n\nExamples:\nlayouts\/home.html.twig # `type` is \"homepage\"\nlayouts\/page.html.twig # `type` is \"page\"\nlayouts\/page.html.fr.twig # `type` is \"page\" and `language` is \"fr\"\nlayouts\/my-layout.html.twig # `layout` is \"my-layout\"\nlayouts\/blog\/list.html.twig # `section` is \"blog\"\nlayouts\/blog\/list.rss.twig # `section` is \"blog\" and `format` is \"rss\"\n<my-site>\n\u251c\u2500 ...\n\u251c\u2500 layouts\n| \u251c\u2500 index.html.twig # Used by type \"homepage\"\n| \u251c\u2500 list.html.twig # Used by types \"homepage\", \"section\" and \"term\"\n| \u251c\u2500 list.rss.twig # Used by types \"homepage\", \"section\" and \"term\", for RSS output format\n| \u251c\u2500 page.html.twig # Used by type \"page\"\n| \u251c\u2500 my-layout.html.twig\n| \u251c\u2500 ...\n| \u2514\u2500 partials # Included templates\n| \u251c\u2500 footer.html.twig\n| \u2514\u2500 ...\n\u2514\u2500 themes # Themes layouts and templates", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#naming-convention", "experimental": "0" }, { "objectID": "documentation/templates#built-in-templates", "page": "Templates", "title": "Built-in templates", "description": "Cecil comes with a set of built-in templates.", "content": "Cecil comes with a set of built-in templates.\nIf you need to modify built-in templates, you can easily extract them via the following command: they will be copied in the layouts directory of your site.\nphp cecil.phar util:templates:extract\nDefault templates\n\n_default\/page.html.twig\nA simple main template with a clean CSS.\n_default\/list.html.twig\nA pages list with (an optional) pagination.\n_default\/list.atom.twig\nAn Atom feed.\n_default\/list.rss.twig\nA RSS feed.\n_default\/vocabulary.html.twig\nA simple list of all terms of a vocabulary.\n_default\/404.html.twig\nA basic error 404 (\"Page not found\") template.\n_default\/sitemap.xml.twig\nThe sitemap.xml template: list of all pages sorted by date.\n_default\/robots.txt.twig\nThe robots.txt template: allow all pages except 404, and add a reference to the sitemap.\n_default\/redirect.html.twig\nThe redirect template.\n\nPartial templates\n\npartials\/navigation.html.twig\nA main menu navigation.\npartials\/paginator.html.twig\nA simple paginated navigation for list templates with \"Previous\" and \"Next\" links.\npartials\/metatags.html.twig\nAll metatags in one template: title, description, canonical, open-graph, twitter card, etc. See metatags configuration.\npartials\/languages.html.twig\nA basic languages switcher.\n\nLookup rules\nIn most of cases you don\u2019t need to specify the layout: Cecil selects the most appropriate layout, according to the page type.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#built-in-templates", "experimental": "0" }, { "objectID": "documentation/templates#homepage-template-lookup", "page": "Templates", "title": "Homepage template lookup", "description": "For example, the HTML output of home page (index.md) will be rendered:", "content": "For example, the HTML output of home page (index.md) will be rendered:\n\nwith my-layout.html.twig if the layout variable is set to \"my-layout\" (in the front matter)\nif not, with home.html.twig if the file exists\nif not, with index.html.twig if the file exists\nif not, with list.html.twig if the file exists\netc.\n\nAll rules are detailed below, for each page type, in the priority order.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#homepage-template-lookup", "experimental": "0" }, { "objectID": "documentation/templates#type-homepage", "page": "Templates", "title": "Type homepage", "description": "", "content": "<layout>.<format>.twig\nindex.<format>.twig\nhome.<format>.twig\nlist.<format>.twig\n_default\/<layout>.<format>.twig\n_default\/index.<format>.twig\n_default\/home.<format>.twig\n_default\/list.<format>.twig\n_default\/page.<format>.twig", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#type-homepage", "experimental": "0" }, { "objectID": "documentation/templates#type-page", "page": "Templates", "title": "Type page", "description": "", "content": "<section>\/<layout>.<format>.twig\n<layout>.<format>.twig\n<section>\/page.<format>.twig\n_default\/<layout>.<format>.twig\npage.<format>.twig\n_default\/page.<format>.twig", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#type-page", "experimental": "0" }, { "objectID": "documentation/templates#type-section", "page": "Templates", "title": "Type section", "description": "", "content": "<layout>.<format>.twig\n<section>\/index.<format>.twig\n<section>\/list.<format>.twig\nsection\/<section>.<format>.twig\n_default\/section.<format>.twig\nlist.<format>.twig\n_default\/list.<format>.twig", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#type-section", "experimental": "0" }, { "objectID": "documentation/templates#type-vocabulary", "page": "Templates", "title": "Type vocabulary", "description": "", "content": "taxonomy\/<plural>.<format>.twig\nvocabulary.<format>.twig\n_default\/vocabulary.<format>.twig", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#type-vocabulary", "experimental": "0" }, { "objectID": "documentation/templates#type-term", "page": "Templates", "title": "Type term", "description": "", "content": "taxonomy\/<term>.<format>.twig\ntaxonomy\/<singular>.<format>.twig\nterm.<format>.twig\n_default\/term.<format>.twig\n_default\/list.<format>.twig\n\nMost of those layouts are available by default, see built-in templates.\nVariables\n\nThe application passes variables to the templates for manipulation in the template. Variables may have attributes or elements you can access, too.\nUse a dot (.) to access attributes of a variable: {{ foo.bar }}\n\nYou can use variables from different scopes: site, page, cecil.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#type-term", "experimental": "0" }, { "objectID": "documentation/templates#site", "page": "Templates", "title": "site", "description": "The site variable contains built-in variables and those set in the configuration.", "content": "The site variable contains built-in variables and those set in the configuration.\n\n\n\nVariable\nDescription\n\n\n\n\nsite.pages\nCollection of all pages, in the current language.\n\n\nsite.allpages\nCollection of all pages, in all languages.\n\n\nsite.page(id)\nA page with the given ID.\n\n\nsite.taxonomies\nCollection of vocabularies.\n\n\nsite.home\nID of the home page.\n\n\nsite.time\nCurrent Timestamp.\n\n\nsite.debug\nDebug mode status (true or false).\n\n\nsite.build\nCurrent build ID.\n\n\n\nExample:\ntitle: \"My amazing website!\"\nCan be displayed in a template with:\n{{ site.title }}\nUse showable method on pages collection to return only published and not virtual\/redirect\/excluded pages.\nExample:\n{% for page in site.pages.showable %}\n<a href=\"{{ url(page) }}\">{{ page.title }}<\/a>\n{% endfor %}\nIn some cases, you can encounter conflicts between configuration and built-in variables (e.g. pages.default configuration). In that case, you can use config.<variable> (where <variable> is the variable name\/path) to access the raw configuration directly.\nExample:\n{{ config.pages.default.sitemap.priority }}\nsite.menus\nLoop on site.menus.<menu> to get each entry of the <menu> collection (e.g.: main).\n\n\n\nVariable\nDescription\n\n\n\n\n<entry>.name\nEntry name.\n\n\n<entry>.url\nEntry URL.\n\n\n<entry>.weight\nEntry weight (useful to sort menu entries).\n\n\n\nExample:\n<nav>\n <ol>\n {% for entry in site.menus.main|sort_by_weight %}\n <li><a href=\"{{ url(entry.url) }}\" data-weight=\"{{ entry.weight }}\">{{ entry.name }}<\/a><\/li>\n {% endfor %}\n <\/ol>\n<\/nav>\nsite.language\nInformation about the current language.\n\n\n\nVariable\nDescription\n\n\n\n\nsite.language\nLanguage code (e.g.: en).\n\n\nsite.language.name\nLanguage name (e.g.: English).\n\n\nsite.language.locale\nLanguage locale code (e.g.: en_US).\n\n\nsite.language.weight\nLanguage position in the languages list.\n\n\n\nYou can retrieve name, locale and weight of a specific language by passing its code as a parameter.\ne.g.: site.language.name('fr').\nsite.static\nThe static files collection can be accessed via site.static if the static load is enabled.\nEach file exposes the following properties:\n\npath: relative path (e.g.: \/images\/img-1.jpg)\ndate: creation date (timestamp)\nupdated: modification date (timestamp)\nname: name (e.g.: img-1.jpg)\nbasename: name without extension (e.g.: img-1)\next: extension (e.g.: jpg)\ntype: media type (e.g.: image)\nsubtype: media sub type (e.g.: image\/jpeg)\nexif: image EXIF data (array)\naudio: Mp3Info object\nvideo: array of basic video information (duration in seconds, width and height)\n\nsite.data\nA data collection can be accessed via site.data.<filename> (without file extension).\nExamples:\n\ndata\/authors.yml : site.data.authors\ndata\/authors.fr.yml : site.data.authors (if site.language = \"fr\")\ndata\/galleries\/gallery-1.json : site.data.galleries.gallery-1", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#site", "experimental": "0" }, { "objectID": "documentation/templates#page", "page": "Templates", "title": "page", "description": "The page variable contains built-in variables of a page and those set in the front matter.", "content": "The page variable contains built-in variables of a page and those set in the front matter.\n\n\n\nVariable\nDescription\nExample\n\n\n\n\npage.id\nUnique identifier.\nblog\/post-1\n\n\npage.title\nFile name (without extension).\nPost 1\n\n\npage.date\nFile creation date.\nDateTime\n\n\npage.body\nFile body.\nMarkdown\n\n\npage.content\nFile body converted in HTML.\nHTML\n\n\npage.section\nFile root folder (slugified).\nblog\n\n\npage.path\nFile path (slugified).\nblog\/post-1\n\n\npage.slug\nFile name (slugified).\npost-1\n\n\npage.filepath\nFile system path.\nBlog\/Post 1.md\n\n\npage.type\nhomepage, page, section, vocabulary or term.\npage\n\n\npage.pages\nCollection of all sub pages.\nCollection\n\n\npage.translations\nCollection of translated pages.\nCollection\n\n\n\nUse showable method on pages collection to return only published and not virtual\/redirect\/excluded pages.\nExample:\n{% for page in page.pages.showable %}\n<a href=\"{{ url(page) }}\">{{ page.title }}<\/a>\n{% endfor %}\npage.<prev\/next>\nNavigation between pages within the same section.\n\n\n\nVariable\nDescription\nExample\n\n\n\n\npage.prev\nPrevious page.\nPage\n\n\npage.next\nNext page.\nPage\n\n\n\nExample:\n<a href=\"{{ url(page.prev) }}\">{{ page.prev.title }}<\/a>\npage.paginator\nPaginator helps you build navigation for list pages: homepage, sections, and taxonomies.\n\n\n\nVariable\nDescription\n\n\n\n\npage.paginator.pages\nPages Collection.\n\n\npage.paginator.pages_total\nNumber total of pages.\n\n\npage.paginator.count\nNumber of paginator's pages.\n\n\npage.paginator.current\nPosition index of the current page.\n\n\npage.paginator.links.first\nPage ID of the first page.\n\n\npage.paginator.links.prev\nPage ID of the previous page.\n\n\npage.paginator.links.self\nPage ID of the current page.\n\n\npage.paginator.links.next\nPage ID of the next page.\n\n\npage.paginator.links.last\nPage ID of the last page.\n\n\npage.paginator.links.path\nPage ID without the position index.\n\n\n\nBecause links entries are Page ID you must use the url() function to create working links.\ne.g: {{ url(page.paginator.links.next) }}\nExample:\n{% if page.paginator %}\n<div>\n {% if page.paginator.links.prev is defined %}\n <a href=\"{{ url(page.paginator.links.prev) }}\">Previous<\/a>\n {% endif %}\n {% if page.paginator.links.next is defined %}\n <a href=\"{{ url(page.paginator.links.next) }}\">Next<\/a>\n {% endif %}\n<\/div>\n{% endif %}\nExample:\n{% if page.paginator %}\n<div>\n {% for paginator_index in 1..page.paginator.count %}\n {% if paginator_index != page.paginator.current %}\n {% if paginator_index == 1 %}\n <a href=\"{{ url(page.paginator.links.first) }}\">{{ paginator_index }}<\/a>\n {% else %}\n <a href=\"{{ url(page.paginator.links.path ~ '\/' ~ paginator_index) }}\">{{ paginator_index }}<\/a>\n {% endif %}\n {% else %}\n {{ paginator_index }}\n {% endif %}\n {% endfor %}\n<\/div>\n{% endif %}\nTaxonomy\nVariables available in vocabulary and term templates.\nVocabulary\n\n\n\nVariable\nDescription\n\n\n\n\npage.plural\nVocabulary name in plural form.\n\n\npage.singular\nVocabulary name in singular form.\n\n\npage.terms\nList of terms (Collection).\n\n\n\nTerm\n\n\n\nVariable\nDescription\n\n\n\n\npage.term\nTerm ID.\n\n\npage.pages\nList of pages in this term (Collection).", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#page", "experimental": "0" }, { "objectID": "documentation/templates#cecil", "page": "Templates", "title": "cecil", "description": "", "content": "Variable\nDescription\n\n\n\n\ncecil.url\nURL of the Cecil website.\n\n\ncecil.version\nCecil current version.\n\n\ncecil.poweredby\nPrint Cecil v%s, with %s is the current version.\n\n\n\nFunctions\n\nFunctions can be called to generate content. Functions are called by their name followed by parentheses (()) and may have arguments.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#cecil", "experimental": "0" }, { "objectID": "documentation/templates#url", "page": "Templates", "title": "url", "description": "Creates a valid URL for a page, a menu entry, an asset, a page ID or a path.", "content": "Creates a valid URL for a page, a menu entry, an asset, a page ID or a path.\n{{ url(value, {options}) }}\n\n\n\nOption\nDescription\nType\nDefault\n\n\n\n\ncanonical\nPrefix URL with baseurl or use canonical.url if exists.\nboolean\nfalse\n\n\nformat\nDefines page output format (e.g.: json).\nstring\nhtml\n\n\nlanguage\nDefines page language (e.g.: fr).\nstring\nnull\n\n\n\nExamples:\n{# page #}\n{{ url(page) }}\n{{ url(page, {canonical: true}) }}\n{{ url(page, {format: json}) }}\n{{ url(page, {language: fr}) }}\n{# menu entry #}\n{{ url(site.menus.main.about) }}\n{# asset #}\n{{ url(asset('styles.css')) }}\n{# page ID #}\n{{ url('page-id') }}\n{# path #}\n{{ url('about-me\/') }}\n{{ url('tags\/' ~ tag) }}\nFor convenience the url function is also available as a filter:\n{# page #}\n{{ page|url }}\n{{ page|url({canonical: true, format: json, language: fr}) }}\n{# asset #}\n{{ asset('styles.css')|url }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#url", "experimental": "0" }, { "objectID": "documentation/templates#asset", "page": "Templates", "title": "asset", "description": "An asset is a resource useable in templates, like CSS, JavaScript, image, audio, video, etc.", "content": "An asset is a resource useable in templates, like CSS, JavaScript, image, audio, video, etc.\nThe asset() function creates an asset object from a file path, an array of files path (bundle) or an URL (remote file), and are processed (minified, fingerprinted, etc.) according to the configuration.\nResource files must be stored in the assets\/ (or static\/) directory.\n{{ asset(path, {options}) }}\n\n\n\nOption\nDescription\nType\nDefault\n\n\n\n\nfilename\nSave bundle to a custom file name.\nstring\nstyles.css or scripts.js\n\n\nignore_missing\nDo not stop build if file is not found.\nboolean\nfalse\n\n\nfingerprint\nAdd content hash to the file name.\nboolean\ntrue\n\n\nminify\nCompress CSS or JavaScript.\nboolean\ntrue\n\n\noptimize\nCompress image.\nboolean\nfalse\n\n\nfallback\nLoad a local asset if remote file is not found.\nstring\n``\n\n\nuseragent\nUser agent key (See Assets configuration).\nstring\ndefault\n\n\n\nYou can use filters to manipulate assets.\nYou don't need to clear the cache after modifying an asset: the cache is automatically cleared when the file is modified or when the file name is changed.\nExamples:\n{# CSS #}\n{{ asset('styles.css') }}\n{# CSS bundle #}\n{{ asset(['poole.css', 'hyde.css'], {filename: styles.css}) }}\n{# JavaScript #}\n{{ asset('scripts.js') }}\n{# image #}\n{{ asset('image.jpeg') }}\n{# audio #}\n{{ asset('audio.mp3') }}\n{# video #}\n{{ asset('video.mp4') }}\n{# remote file #}\n{{ asset('https:\/\/cdnjs.cloudflare.com\/ajax\/libs\/anchor-js\/4.3.1\/anchor.min.js', {minify: false}) }}\n{# with filter #}\n{{ asset('styles.css')|minify }}\n{{ asset('styles.scss')|to_css|minify }}\nAsset attributes\nAssets created with the asset() function expose some useful attributes.\nCommon:\n\nfile: filesystem path\nmissing: true if file is not found but missing is allowed\npath: public path\next: file extension\ntype: media type (e.g.: image)\nsubtype: media sub type (e.g.: image\/jpeg)\nsize: size in octets\ncontent: file content\nhash: file content hash (md5)\ndataurl: data URL encoded in Base64\nintegrity: integrity hash\n\nRemote:\n\nurl: URL of the remote file\n\nBundle:\n\nfiles: array of filesystem path in case of a bundle\n\nImage:\n\nwidth: image width in pixels\nheight: image height in pixels\nexif: image EXIF data as array\n\nAudio:\n\nduration: duration in seconds.microseconds\nbitrate: bitrate in bps\nchannel: 'stereo', 'dual_mono', 'joint_stereo' or 'mono'\n\nVideo:\n\nduration: duration in seconds\nwidth: width in pixels\nheight: height in pixels\n\nExamples:\n{# image width in pixels #}\n{{ asset('image.png').width }}px\n{# photo's date in seconds #}\n{{ asset('photo.jpeg').exif.EXIF.DateTimeOriginal|date('U') }}\n{# audio duration in seconds #}\n{{ asset('song.mp3').duration|round }} s\n{# video duration in seconds #}\n{{ asset('movie.mp4').duration|round }} s\n{# file integrity hash #}\n{% set integrity = asset('styles.scss').integrity %}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#asset", "experimental": "0" }, { "objectID": "documentation/templates#integrity", "page": "Templates", "title": "integrity", "description": "Creates the hash (sha384) of a file (from an asset or a path).", "content": "Creates the hash (sha384) of a file (from an asset or a path).\n{{ integrity(asset) }}\nUsed for SRI (Subresource Integrity).\nExample:\n{{ integrity('styles.css') }}\n{# sha384-oGDH3qCjzMm\/vI+jF4U5kdQW0eAydL8ZqXjHaLLGduOsvhPRED9v3el\/sbiLa\/9g #}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#integrity", "experimental": "0" }, { "objectID": "documentation/templates#html", "page": "Templates", "title": "html", "description": "Creates an HTML element from an asset (or an array of assets with custom attributes).", "content": "Creates an HTML element from an asset (or an array of assets with custom attributes).\n{{ html(asset, {attributes}, {options}) }}\n{# dedicated functions for each common type of asset #}\n{{ css(asset) }}\n{{ js(asset) }}\n{{ image(asset) }}\n{{ audio(asset) }}\n{{ video(asset) }}\n\n\n\nOption\nDescription\nType\n\n\n\n\nattributes\nAdds name=\"value\" couple to the HTML element.\narray\n\n\noptions\n{preload: boolean}: preloads.For images:{formats: array}: adds alternative formats.{responsive: bool|string}: adds responsive images (based on width or pixels density).\narray\n\n\n\nSince version 8.42.0, the html function replace the deprecated html filter.\nYou can define a global default behavior of images options (formats and responsive) through the layouts configuration.\nExamples:\n{# CSS with an attribute #}\n{{ html(asset('print.css'), {media: 'print'}) }}\n{# CSS with an attribute and an option #}\n{{ html(asset('styles.css'), {title: 'Main theme'}, {preload: true}) }}\n{# Array of assets with media query #}\n{{ html([\n {asset: asset('css\/style.css')},\n {asset: asset('css\/style-dark.css'), attributes: {media: '(prefers-color-scheme: dark)'}}\n]) }}\n{# JavaScript #}\n{{ html(asset('script.js')) }}\n{# image without specific attributes nor options #}\n{{ html(asset('image.png')) }}\n{# image with specific attributes, responsive images and alternative formats #}\n{{ html(asset('image.jpg'), {alt: 'Description', loading: 'lazy'}, {responsive: true, formats: ['avif', 'webp']}) }}\n{# image with responsive pixels density images #}\n{{ html(asset('image.jpg'), options={responsive: 'density'}, attributes={width: 256}) }}\n{# Audio #}\n{{ html(asset('audio.mp3')) }}\n{# Video #}\n{{ html(asset('video.mp4')) }}\nFor convenience the html function stay available as a filter (but is considered as deprecated):\n{{ asset|html({attributes}, {options}) }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#html", "experimental": "0" }, { "objectID": "documentation/templates#image-srcset", "page": "Templates", "title": "image_srcset", "description": "Builds the HTML img srcset (responsive) attribute of an image Asset.", "content": "Builds the HTML img srcset (responsive) attribute of an image Asset.\n{{ image_srcset(asset) }}\nExamples:\n{% set asset = asset(image_path) %}\n<img src=\"{{ url(asset) }}\" width=\"{{ asset.width }}\" height=\"{{ asset.height }}\" alt=\"\" class=\"asset\" srcset=\"{{ image_srcset(asset) }}\" sizes=\"{{ image_sizes('asset') }}\">", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#image-srcset", "experimental": "0" }, { "objectID": "documentation/templates#image-sizes", "page": "Templates", "title": "image_sizes", "description": "Returns the HTML img sizes attribute based on a CSS class name.\nIt should be use in conjunction with the image_srcset function.", "content": "Returns the HTML img sizes attribute based on a CSS class name.\nIt should be use in conjunction with the image_srcset function.\n{{ image_sizes('class') }}\nExamples:\n{% set asset = asset(image_path) %}\n<img src=\"{{ url(asset) }}\" width=\"{{ asset.width }}\" height=\"{{ asset.height }}\" alt=\"\" class=\"asset\" srcset=\"{{ image_srcset(asset) }}\" sizes=\"{{ image_sizes('asset') }}\">", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#image-sizes", "experimental": "0" }, { "objectID": "documentation/templates#image-from-website", "page": "Templates", "title": "image_from_website", "description": "Builds the HTML img element from a website URL by extracting the image from meta tags.", "content": "Builds the HTML img element from a website URL by extracting the image from meta tags.\n{{ image_from_website('url') }}\nExamples:\n{{ image_from_website('https:\/\/example.com\/page-with-image.html') }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#image-from-website", "experimental": "0" }, { "objectID": "documentation/templates#readtime", "page": "Templates", "title": "readtime", "description": "Determines read time of a text, in minutes.", "content": "Determines read time of a text, in minutes.\n{{ readtime(value) }}\nExample:\n{{ readtime(page.content) }} min", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#readtime", "experimental": "0" }, { "objectID": "documentation/templates#hash", "page": "Templates", "title": "hash", "description": "Calculates the hash of an object, an array or a string with a given algorithm.", "content": "Calculates the hash of an object, an array or a string with a given algorithm.\n{{ hash(value, algorithm) }}\nalgorithm can be any algorithm supported by PHP's hash() function (e.g.: md5, sha256, etc.). Default is xxh128.\nExample:\n{{ hash('my string', 'sha256') }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#hash", "experimental": "0" }, { "objectID": "documentation/templates#cache-key", "page": "Templates", "title": "cache_key", "description": "Calculates a cache key for fragments cache based on a name and an optional value.", "content": "Calculates a cache key for fragments cache based on a name and an optional value.\n{% cache cache_key(name, value) %}\n {# cacheable content #}\n{% endcache %}\nThe function adds a hash of the value (could be a string, an array or an object) to the name (and the current language and build ID to be sure the generated cache key is unique) so if the value is changed the cache key is changed too and the cache is automatically cleared.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#cache-key", "experimental": "0" }, { "objectID": "documentation/templates#getenv", "page": "Templates", "title": "getenv", "description": "Gets the value of an environment variable from its key.", "content": "Gets the value of an environment variable from its key.\n{{ getenv(var) }}\nExample:\n{{ getenv('VAR') }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#getenv", "experimental": "0" }, { "objectID": "documentation/templates#dump", "page": "Templates", "title": "dump", "description": "The dump function dumps information about a template variable. This is mostly useful to debug a template that does not behave as expected by introspecting its variables:", "content": "The dump function dumps information about a template variable. This is mostly useful to debug a template that does not behave as expected by introspecting its variables:\n{{ dump(user) }}\nThe debug mode must be enabled.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#dump", "experimental": "0" }, { "objectID": "documentation/templates#d", "page": "Templates", "title": "d", "description": "The d() function is the HTML version of dump() and use the Symfony VarDumper Component behind the scenes.", "content": "The d() function is the HTML version of dump() and use the Symfony VarDumper Component behind the scenes.\n{{ d(variable, {theme: light}) }}\n\nIf variable is not provided then the function returns the current Twig context\nAvailable themes are \u00ab light \u00bb (default) and \u00ab dark \u00bb\n\nThe debug mode must be enabled.\nSorts\nSorting collections (of pages, menus or taxonomies).", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#d", "experimental": "0" }, { "objectID": "documentation/templates#sort-by-title", "page": "Templates", "title": "sort_by_title", "description": "Sorts a collection by title (with natural sort).", "content": "Sorts a collection by title (with natural sort).\n{{ collection|sort_by_title }}\nExample:\n{{ site.pages|sort_by_title }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#sort-by-title", "experimental": "0" }, { "objectID": "documentation/templates#sort-by-date", "page": "Templates", "title": "sort_by_date", "description": "Sorts a collection by date (most recent first).", "content": "Sorts a collection by date (most recent first).\n{{ collection|sort_by_date(variable='date', desc_title=false) }}\nExample:\n{# sort by date #}\n{{ site.pages|sort_by_date }}\n{# sort by updated variable instead of date #}\n{{ site.pages|sort_by_date(variable='updated') }}\n{# sort items with the same date by desc title #}\n{{ site.pages|sort_by_date(desc_title=true) }}\n{# reverse sort #}\n{{ site.pages|sort_by_date|reverse }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#sort-by-date", "experimental": "0" }, { "objectID": "documentation/templates#sort-by-weight", "page": "Templates", "title": "sort_by_weight", "description": "Sorts a collection by weight (lighter first).", "content": "Sorts a collection by weight (lighter first).\n{{ collection|sort_by_weight }}\nExample:\n{{ site.menus.main|sort_by_weight }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#sort-by-weight", "experimental": "0" }, { "objectID": "documentation/templates#sort", "page": "Templates", "title": "sort", "description": "For more complex cases, you should use Twig\u2019s native sort.", "content": "For more complex cases, you should use Twig\u2019s native sort.\nExample:\n{% set files = site.static|sort((a, b) => a.date|date('U') < b.date|date('U')) %}\nFilters\nVariables can be modified by filters. Filters are separated from the variable by a pipe symbol (|). Multiple filters can be chained. The output of one filter is applied to the next.\n{{ page.title|truncate(25)|capitalize }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#sort", "experimental": "0" }, { "objectID": "documentation/templates#filter-by", "page": "Templates", "title": "filter_by", "description": "Filters a pages collection by variable name\/value.", "content": "Filters a pages collection by variable name\/value.\n{{ collection|filter_by(variable, value) }}\nExample:\n{{ pages|filter_by('section', 'blog') }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#filter-by", "experimental": "0" }, { "objectID": "documentation/templates#filter", "page": "Templates", "title": "filter", "description": "For more complex cases, you should use Twig\u2019s native filter.", "content": "For more complex cases, you should use Twig\u2019s native filter.\nExample:\n{% pages|filter(p => p.virtual == false and p.id not in ['page-1', 'page-2']) %}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#filter", "experimental": "0" }, { "objectID": "documentation/templates#markdown-to-html", "page": "Templates", "title": "markdown_to_html", "description": "Converts a Markdown string to HTML.", "content": "Converts a Markdown string to HTML.\n{{ markdown|markdown_to_html }}\n{% apply markdown_to_html %}\n{# Markdown here #}\n{% endapply %}\nExamples:\n{% set markdown = '**This is bold text**' %}\n{{ markdown|markdown_to_html }}\n{% apply markdown_to_html %}\n**This is bold text**\n{% endapply %}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#markdown-to-html", "experimental": "0" }, { "objectID": "documentation/templates#toc", "page": "Templates", "title": "toc", "description": "Extracts only headings matching the given selectors (h2, h3, etc.), or those defined in config pages.body.toc if not specified.\nThe format parameter defines the output format: html or json.\nThe url parameter is used to build links to headings.", "content": "Extracts only headings matching the given selectors (h2, h3, etc.), or those defined in config pages.body.toc if not specified.\nThe format parameter defines the output format: html or json.\nThe url parameter is used to build links to headings.\n{{ markdown|toc(format, selectors, url) }}\nExamples:\n{{ page.body|toc }}\n{{ page.body|toc('html') }}\n{{ page.body|toc(selectors=['h2']) }}\n{{ page.body|toc(url=url(page)) }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#toc", "experimental": "0" }, { "objectID": "documentation/templates#json-decode", "page": "Templates", "title": "json_decode", "description": "Converts a JSON string to an array.", "content": "Converts a JSON string to an array.\n{{ json|json_decode }}\nExample:\n{% set json = '{\"foo\": \"bar\"}' %}\n{% set array = json|json_decode %}\n{{ array.foo }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#json-decode", "experimental": "0" }, { "objectID": "documentation/templates#yaml-parse", "page": "Templates", "title": "yaml_parse", "description": "Converts a YAML string to an array.", "content": "Converts a YAML string to an array.\n{{ yaml|yaml_parse }}\nExample:\n{% set yaml = 'key: value' %}\n{% set array = yaml|yaml_parse %}\n{{ array.key }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#yaml-parse", "experimental": "0" }, { "objectID": "documentation/templates#slugify", "page": "Templates", "title": "slugify", "description": "Converts a string to a slug.", "content": "Converts a string to a slug.\n{{ string|slugify }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#slugify", "experimental": "0" }, { "objectID": "documentation/templates#u", "page": "Templates", "title": "u", "description": "The u filter wraps a text in a Unicode object (a Symfony UnicodeString instance) that exposes methods to \"manipulate\" the string.", "content": "The u filter wraps a text in a Unicode object (a Symfony UnicodeString instance) that exposes methods to \"manipulate\" the string.\nExample:\n{{ 'cecil_string with twig'|u.camel.title }}\n\nCecilStringWithTwig", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#u", "experimental": "0" }, { "objectID": "documentation/templates#singular", "page": "Templates", "title": "singular", "description": "The singular filter transforms a given noun in its plural form into its singular version.", "content": "The singular filter transforms a given noun in its plural form into its singular version.\n{{ string|singular(locale)}}\nExample:\n{# English (en) rules are used by default #}\n{{ 'partitions'|singular }}\n\npartition\n\n{{ 'partitions'|singular('fr') }}\n\npartition", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#singular", "experimental": "0" }, { "objectID": "documentation/templates#plural", "page": "Templates", "title": "plural", "description": "The plural filter transforms a given noun in its singular form into its plural version.", "content": "The plural filter transforms a given noun in its singular form into its plural version.\n{{ string|plural(locale)}}\nExample:\n{# English (en) rules are used by default #}\n{{ 'animal'|plural }}\n\nanimals\n\n{{ 'animal'|plural('fr') }}\n\nanimaux", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#plural", "experimental": "0" }, { "objectID": "documentation/templates#excerpt", "page": "Templates", "title": "excerpt", "description": "Truncates a string and appends suffix.", "content": "Truncates a string and appends suffix.\n{{ string|excerpt(length, suffix) }}\n\n\n\nOption\nDescription\nType\nDefault\n\n\n\n\nlength\nTruncates after this number of characters.\ninteger\n450\n\n\nsuffix\nAppends characters.\nstring\n\u2026\n\n\n\nExamples:\n{{ variable|excerpt }}\n{{ variable|excerpt(250, '...') }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#excerpt", "experimental": "0" }, { "objectID": "documentation/templates#excerpt-html", "page": "Templates", "title": "excerpt_html", "description": "Reads characters before or after <!-- excerpt --> or <!-- break --> tag.\nSee Content documentation for details.", "content": "Reads characters before or after <!-- excerpt --> or <!-- break --> tag.\nSee Content documentation for details.\n{{ string|excerpt_html({separator, capture}) }}\n\n\n\nOption\nDescription\nType\nDefault\n\n\n\n\nseparator\nString to use as separator.\nstring\nexcerpt|break\n\n\ncapture\nPart to capture, before or after the separator.\nstring\nbefore\n\n\n\nExamples:\n{{ variable|excerpt_html }}\n{{ variable|excerpt_html({separator: 'excerpt|break', capture: 'before'}) }}\n{{ variable|excerpt_html({capture: 'after'}) }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#excerpt-html", "experimental": "0" }, { "objectID": "documentation/templates#highlight", "page": "Templates", "title": "highlight", "description": "Highlights a code string with highlight.php.", "content": "Highlights a code string with highlight.php.\n{{ code|highlight(language) }}\nExamples:\n{{ '<?php echo $highlighted->value; ?>'|highlight('php') }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#highlight", "experimental": "0" }, { "objectID": "documentation/templates#to-css", "page": "Templates", "title": "to_css", "description": "Compiles a Sass file to CSS.", "content": "Compiles a Sass file to CSS.\n{{ asset(path)|to_css }}\n{{ path|to_css }}\nExamples:\n{{ asset('styles.scss')|to_css }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#to-css", "experimental": "0" }, { "objectID": "documentation/templates#fingerprint", "page": "Templates", "title": "fingerprint", "description": "Add the file content finger print to the file name.", "content": "Add the file content finger print to the file name.\n{{ asset(path)|fingerprint }}\n{{ path|fingerprint }}\nExamples:\n{{ asset('styles.css')|fingerprint }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#fingerprint", "experimental": "0" }, { "objectID": "documentation/templates#minify", "page": "Templates", "title": "minify", "description": "Minifying a CSS or a JavaScript file.", "content": "Minifying a CSS or a JavaScript file.\n{{ asset(path)|minify }}\nExamples:\n{{ asset('styles.css')|minify }}\n{{ asset('scripts.js')|minify }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#minify", "experimental": "0" }, { "objectID": "documentation/templates#minify-css", "page": "Templates", "title": "minify_css", "description": "Minifying a CSS string.", "content": "Minifying a CSS string.\n{{ variable|minify_css }}\n{% apply minify_css %}\n{# CSS here #}\n{% endapply %}\nExamples:\n{% set styles = 'some CSS here' %}\n{{ styles|minify_css }}\n<style>\n{% apply minify_css %}\n html {\n background-color: #fcfcfc;\n color: #444;\n }\n{% endapply %}\n<\/style>", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#minify-css", "experimental": "0" }, { "objectID": "documentation/templates#minify-js", "page": "Templates", "title": "minify_js", "description": "Minifying a JavaScript string.", "content": "Minifying a JavaScript string.\n{{ variable|minify_js }}\n{% apply minify_js %}\n{# JavaScript here #}\n{% endapply %}\nExamples:\n{% set script = 'some JavaScript here' %}\n{{ script|minify_js }}\n<script>\n{% apply minify_js %}\n var test = 'test';\n console.log(test);\n{% endapply %}\n<\/script>", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#minify-js", "experimental": "0" }, { "objectID": "documentation/templates#scss-to-css", "page": "Templates", "title": "scss_to_css", "description": "Compiles a Sass string to CSS.", "content": "Compiles a Sass string to CSS.\n{{ variable|scss_to_css }}\n{% apply scss_to_css %}\n{# SCSS here #}\n{% endapply %}\nAlias: sass_to_css.\nExamples:\n{% set scss = 'some SCSS here' %}\n{{ scss|scss_to_css }}\n<style>\n{% apply scss_to_css %}\n $color: #fcfcfc;\n div {\n color: lighten($color, 20%);\n }\n{% endapply %}\n<\/style>", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#scss-to-css", "experimental": "0" }, { "objectID": "documentation/templates#resize", "page": "Templates", "title": "resize", "description": "Resizes an image to a specified width (in pixels) or\/and height (in pixels).", "content": "Resizes an image to a specified width (in pixels) or\/and height (in pixels).\n\nIf only the width is specified, the height is calculated to preserve the aspect ratio\nIf only the height is specified, the width is calculated to preserve the aspect ratio\nIf both width and height are specified, the image is resized to fit within the given dimensions, image is cropped and centered if necessary\nIf remove_animation is true, any animation in the image (e.g., GIF) will be removed\n\n{{ asset(image_path)|resize(width: width, height: height, remove_animation: bool) }}\nThe original file is not altered and the resized version is saved at \/thumbnails\/<width>x<height>\/image.jpg.\nExamples:\n{{ asset(page.image)|resize(300) }}\n{# equivalent to: #}\n{{ asset(page.image)|resize(width: 300) }}\n{# resizes to 300px width, height auto-calculated to preserve aspect ratio #}\n{{ asset(page.image)|resize(height: 200) }}\n{# resizes to 300px width and 200px height, and crops if necessary #}\n{{ asset(page.image)|resize(300, 200) }}\n{# removes any animation from the image #}\n{{ asset(page.image)|resize(width: 1200, height: 630, remove_animation: true) }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#resize", "experimental": "0" }, { "objectID": "documentation/templates#cover", "page": "Templates", "title": "cover", "description": "Resizes an image to a specified width and height, cropping it if necessary.", "content": "Resizes an image to a specified width and height, cropping it if necessary.\nThe cover filter is deprecated since version 8.77 and will be removed in future versions. Use the resize filter instead, with both width and height parameters.\n{{ asset(image_path)|cover(width, height) }}\nExample:\n{{ asset(page.image)|cover(1200, 630) }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#cover", "experimental": "0" }, { "objectID": "documentation/templates#maskable", "page": "Templates", "title": "maskable", "description": "Adds padding, in pourcentages, to an image to make it maskable.", "content": "Adds padding, in pourcentages, to an image to make it maskable.\n{{ asset(image_path)|maskable(padding) }}\nExample:\n{{ asset('icon.png')|maskable }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#maskable", "experimental": "0" }, { "objectID": "documentation/templates#webp", "page": "Templates", "title": "webp", "description": "Converts an image to WebP format.", "content": "Converts an image to WebP format.\nExample:\n<picture>\n <source type=\"image\/webp\" srcset=\"{{ asset(image_path)|webp }}\">\n <img src=\"{{ url(asset(image_path)) }}\" width=\"{{ asset(image_path).width }}\" height=\"{{ asset(image_path).height }}\" alt=\"\">\n<\/picture>", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#webp", "experimental": "0" }, { "objectID": "documentation/templates#avif", "page": "Templates", "title": "avif", "description": "Converts an image to AVIF format.", "content": "Converts an image to AVIF format.\nExample:\n<picture>\n <source type=\"image\/avif\" srcset=\"{{ asset(image_path)|avif }}\">\n <img src=\"{{ url(asset(image_path)) }}\" width=\"{{ asset(image_path).width }}\" height=\"{{ asset(image_path).height }}\" alt=\"\">\n<\/picture>", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#avif", "experimental": "0" }, { "objectID": "documentation/templates#dataurl", "page": "Templates", "title": "dataurl", "description": "Returns the data URL of an asset.", "content": "Returns the data URL of an asset.\n{{ asset(path)|dataurl }}\n{{ asset(image_path)|dataurl }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#dataurl", "experimental": "0" }, { "objectID": "documentation/templates#lqip", "page": "Templates", "title": "lqip", "description": "Returns a Low Quality Image Placeholder (100x100 px, 50% blurred) as data URL.", "content": "Returns a Low Quality Image Placeholder (100x100 px, 50% blurred) as data URL.\n{{ asset(image_path)|lqip }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#lqip", "experimental": "0" }, { "objectID": "documentation/templates#dominant-color", "page": "Templates", "title": "dominant_color", "description": "Returns the dominant hexadecimal color of an image.", "content": "Returns the dominant hexadecimal color of an image.\n{{ asset(image_path)|dominant_color }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#dominant-color", "experimental": "0" }, { "objectID": "documentation/templates#inline", "page": "Templates", "title": "inline", "description": "Outputs the content of an Asset.", "content": "Outputs the content of an Asset.\n{{ asset(path)|inline }}\nExample:\n{{ asset('styles.css')|inline }}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#inline", "experimental": "0" }, { "objectID": "documentation/templates#preg-split", "page": "Templates", "title": "preg_split", "description": "Splits a string into an array using a regular expression.", "content": "Splits a string into an array using a regular expression.\n{{ string|preg_split(pattern, limit) }}\nExample:\n{% set headers = page.content|preg_split('\/<br[^>]*>\/') %}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#preg-split", "experimental": "0" }, { "objectID": "documentation/templates#preg-match-all", "page": "Templates", "title": "preg_match_all", "description": "Performs a regular expression match and return the group for all matches.", "content": "Performs a regular expression match and return the group for all matches.\n{{ string|preg_match_all(pattern, group) }}\nExample:\n{% set tags = page.content|preg_match_all('\/<[^>]+>(.*)<\\\/[^>]+>\/') %}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#preg-match-all", "experimental": "0" }, { "objectID": "documentation/templates#hex-to-rgb", "page": "Templates", "title": "hex_to_rgb", "description": "Converts a hexadecimal color to RGB.", "content": "Converts a hexadecimal color to RGB.\n{{ color|hex_to_rgb }}\nLocalization\nCecil support text translation and date localization.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#hex-to-rgb", "experimental": "0" }, { "objectID": "documentation/templates#text-translation", "page": "Templates", "title": "Text translation", "description": "Uses the trans tag or filter to translate texts in templates.", "content": "Uses the trans tag or filter to translate texts in templates.\n{% trans with variables into locale %}{% endtrans %}\n{{ message|trans(variables = []) }}\nExamples\n{% trans %}Hello World!{% endtrans %}\n{{ message|trans }}\nInclude variables:\n{% trans with {'%name%': 'Arnaud'} %}Hello %name%!{% endtrans %}\n{{ message|trans({'%name%': 'Arnaud'}) }}\nForce locale:\n{% trans into 'fr_FR' %}Hello World!{% endtrans %}\nPluralize:\n{% trans with {'%count%': 42}%}{0}I don't have apples|{1}I have one apple|]1,Inf[I have %count% apples{% endtrans %}", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#text-translation", "experimental": "0" }, { "objectID": "documentation/templates#translation-files", "page": "Templates", "title": "Translation files", "description": "Translation files must be named messages.<locale>.<format> and stored in the translations directory.\nCecil supports yaml and mo (Gettext) file formats by default.", "content": "Translation files must be named messages.<locale>.<format> and stored in the translations directory.\nCecil supports yaml and mo (Gettext) file formats by default.\nThe locale code (e.g.: fr_FR) of a language is defined in the languages entries of the configuration.\nExample:\n<mywebsite>\n\u2514\u2500 translations\n \u251c\u2500 messages.fr_FR.mo <- Machine Object format\n \u2514\u2500 messages.fr_FR.yaml <- Yaml format\nYou can easily extract translations from your templates with the following command:\nphp cecil.phar util:translations:extract\nPoedit is a simple and cross platform translation editor for gettext (PO), and Poedit Pro supports extraction of translation strings from templates out of the box.\nBe careful about the cache when you update translations files.\nCache can be cleared with with the following command:\nphp cecil.phar cache:clear:translations`", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#translation-files", "experimental": "0" }, { "objectID": "documentation/templates#date-localization", "page": "Templates", "title": "Date localization", "description": "Uses the Twig format_date filter to localize a date in templates.", "content": "Uses the Twig format_date filter to localize a date in templates.\n{{ page.date|format_date('long') }}\n{# September 30, 2022 #}\nSupported values are: short, medium, long, and full.\nIf you want to use the format_date filter with other locales than \"en\", you should install the intl PHP extension.\nComponents\nCecil provides a components logic to give you the power making reusable template \"units\".\nThe components feature is provided by the Twig components extension created by Giorgio Pogliani.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#date-localization", "experimental": "0" }, { "objectID": "documentation/templates#components-syntax", "page": "Templates", "title": "Components syntax", "description": "Components are just Twig templates stored in the components\/ subdirectory and can be used anywhere in your templates:", "content": "Components are just Twig templates stored in the components\/ subdirectory and can be used anywhere in your templates:\n{# \/components\/button.twig #}\n<button {{ attributes.merge({class: 'rounded px-4'}) }}>\n {{ slot }}\n<\/button>\n\nThe slot variable is any content you will add between the opening and the close tag.\n\nTo reach a component you need to use the dedicated tag x followed by : and the filename of your component without extension:\n{# \/index.twig #}\n{% x:button with {class: 'text-white'} %}\n <strong>Click me<\/strong>\n{% endx %}\nIt will render:\n<button class=\"text-white rounded px-4\">\n <strong>Click me<\/strong>\n<\/button>\nCache\nCecil uses a cache system to speed up the generation process, it can be disabled or cleared.\nThere are three cache types involved in template rendering: templates, assets, and translations.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#components-syntax", "experimental": "0" }, { "objectID": "documentation/templates#clear-cache", "page": "Templates", "title": "Clear cache", "description": "You can clear the cache with the following commands:", "content": "You can clear the cache with the following commands:\nphp cecil.phar cache:clear # clear all caches\nphp cecil.phar cache:clear:assets # clear assets cache\nphp cecil.phar cache:clear:templates # clear templates cache\nphp cecil.phar cache:clear:translations # clear translations cache\nIn practice you don't need to clear the cache manually, Cecil does it for you when needed (e.g. when files change).", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#clear-cache", "experimental": "0" }, { "objectID": "documentation/templates#fragments-cache", "page": "Templates", "title": "Fragments cache", "description": "Cecil provides a way to cache parts of templates rendering to avoid re-rendering the same partial content multiple times.", "content": "Cecil provides a way to cache parts of templates rendering to avoid re-rendering the same partial content multiple times.\nTo use fragments cache, you must wrap the content you want to cache with the cache tag.\n{% cache 'unique-key' %}\n {# cacheable content #}\n{% endcache %}\nYou should use the cache_key function to be sure to have a unique cache key for each content you want to cache.\nFragments cache is persistent, so if the cache key is too generic, you may end up with wrong content displayed.\nTo clear fragments cache only, you can use the following command:\nphp cecil.phar cache:clear:templates --fragments", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#fragments-cache", "experimental": "0" }, { "objectID": "documentation/templates#disable-cache", "page": "Templates", "title": "Disable cache", "description": "You can disable cache with the configuration.", "content": "You can disable cache with the configuration.\nDisabling cache can slow down the generation process, so it's not recommended.\nDuring local development, if you need to clear cache before each generation, you can use the following option:\nphp cecil.phar serve --clear-cache # clear all caches\nphp cecil.phar serve --clear-cache=<regex> # clear cache for cache key matches with the regular expression <regex>\nExample:\nphp cecil.phar serve --clear-cache=css # clear cache for all CSS files\nExtend", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#disable-cache", "experimental": "0" }, { "objectID": "documentation/templates#functions-and-filters", "page": "Templates", "title": "Functions and filters", "description": "You can add custom functions and custom filters with a Twig extension.", "content": "You can add custom functions and custom filters with a Twig extension.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#functions-and-filters", "experimental": "0" }, { "objectID": "documentation/templates#theme", "page": "Templates", "title": "Theme", "description": "It\u2019s easy to build a theme, you just have to create a folder <theme> with the following structure (like a website but without pages):", "content": "It\u2019s easy to build a theme, you just have to create a folder <theme> with the following structure (like a website but without pages):\n<mywebsite>\n\u2514\u2500 themes\n \u2514\u2500 <theme>\n \u251c\u2500 config.yml\n \u251c\u2500 assets\n \u251c\u2500 layouts\n \u251c\u2500 static\n \u2514\u2500 translations", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/templates/#theme", "experimental": "0" }, { "objectID": "documentation/configuration#title", "page": "Configuration", "title": "title", "description": "Main title of the site.", "content": "Main title of the site.\ntitle: \"<site title>\"", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#title", "experimental": "0" }, { "objectID": "documentation/configuration#baseline", "page": "Configuration", "title": "baseline", "description": "Short description (~ 20 characters).", "content": "Short description (~ 20 characters).\nbaseline: \"<baseline>\"", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#baseline", "experimental": "0" }, { "objectID": "documentation/configuration#baseurl", "page": "Configuration", "title": "baseurl", "description": "The base URL.", "content": "The base URL.\nbaseurl: <url>\nExample:\nbaseurl: http:\/\/localhost:8000\/\nbaseurl should end with a trailing slash (\/).", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#baseurl", "experimental": "0" }, { "objectID": "documentation/configuration#canonicalurl", "page": "Configuration", "title": "canonicalurl", "description": "If set to true the url() function will return the absolute URL (false by default).", "content": "If set to true the url() function will return the absolute URL (false by default).\ncanonicalurl: <true|false> # false by default", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#canonicalurl", "experimental": "0" }, { "objectID": "documentation/configuration#description", "page": "Configuration", "title": "description", "description": "Site description (~ 250 characters).", "content": "Site description (~ 250 characters).\ndescription: \"<description>\"", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#description", "experimental": "0" }, { "objectID": "documentation/configuration#menus", "page": "Configuration", "title": "menus", "description": "Menus are used to create navigation links in templates.", "content": "Menus are used to create navigation links in templates.\nA menu is made up of a unique ID and entry properties (name, URL, weight).\nmenus:\n <name>:\n - id: <unique-id> # unique identifier (required)\n name: \"<name>\" # name displayed in templates\n url: <url> # relative or absolute URL\n weight: <integer> # integer value used to sort entries (lighter first)\nExample:\nmenus:\n main:\n - id: about\n name: \"About\"\n url: \/about\/\n weight: 1\n footer:\n - id: author\n name: The author\n url: https:\/\/arnaudligny.fr\n weight: 99\nA main menu is automatically created with the home page entry and all sections entries (See content management)\nA page can be added to a menu by setting the menu variable in its front matter.\nOverride an entry\nA page menu entry can be overridden: use the page ID as id.\nExample:\nmenus:\n main:\n - id: index\n name: \"My amazing homepage!\"\n weight: 1\nDisable an entry\nA menu entry can be disabled with enabled: false.\nExample:\nmenus:\n main:\n - id: about\n enabled: false", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#menus", "experimental": "0" }, { "objectID": "documentation/configuration#taxonomies", "page": "Configuration", "title": "taxonomies", "description": "List of vocabularies, paired by plural and singular value.", "content": "List of vocabularies, paired by plural and singular value.\ntaxonomies:\n <plural>: <singular>\nExample:\ntaxonomies:\n categories: category\n tags: tag\nThen you can use those vocabularies in your content\u2019s front matter.\nSince version 8.37.0, default vocabularies category and tag have been removed. You must define them in the configuration file if you want to use them.\nA vocabulary can be disabled with the special value disabled. Example: tags: disabled.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#taxonomies", "experimental": "0" }, { "objectID": "documentation/configuration#theme", "page": "Configuration", "title": "theme", "description": "The theme to use, or a list of themes.", "content": "The theme to use, or a list of themes.\ntheme: <theme> # theme name\n# or\ntheme:\n - <theme1> # theme name\n - <theme2>\nThe first theme overrides the others, and so on.\nExamples:\ntheme: hyde\ntheme:\n - serviceworker\n - hyde\nSee themes on GitHub or on website themes section.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#theme", "experimental": "0" }, { "objectID": "documentation/configuration#date", "page": "Configuration", "title": "date", "description": "Date format and timezone.", "content": "Date format and timezone.\ndate:\n format: <format> # date format (optional, `F j, Y` by default)\n timezone: <timezone> # date timezone (optional, local time zone by default)\n\nformat: PHP date format specifier\ntimezone: see timezones\n\nExample:\ndate:\n format: 'j F, Y'\n timezone: 'Europe\/Paris'", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#date", "experimental": "0" }, { "objectID": "documentation/configuration#language", "page": "Configuration", "title": "language", "description": "The main language, defined by its code.", "content": "The main language, defined by its code.\nlanguage: <code> # unique code (`en` by default)\nBy default only others languages pages path are prefixed with its language code, but you can prefix the path of the main language pages with the following option:\n#language: <code>\nlanguage:\n code: <code>\n prefix: true\nWhen prefix is set to true, an alias is automatically created for the home page that redirect from\/ to \/<code>\/.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#language", "experimental": "0" }, { "objectID": "documentation/configuration#languages", "page": "Configuration", "title": "languages", "description": "Options of available languages, used for pages and templates localization.", "content": "Options of available languages, used for pages and templates localization.\nlanguages:\n - code: <code> # unique code (e.g.: `en`, `fr`, 'en-US', `fr-CA`)\n name: <name> # human readable name (e.g.: `Fran\u00e7ais`)\n locale: <locale> # locale code (`language_COUNTRY`, e.g.: `en_US`, `fr_FR`, `fr_CA`)\n enabled: <true|false> # enabled or not (`true` by default)\nExample:\nlanguage: en\nlanguages:\n - code: en\n name: English\n locale: en_US\n - code: fr\n name: Fran\u00e7ais\n locale: fr_FR\nA locale code list is available if needed.\nLocalize\nTo localize configuration options you must store them under the config key of the language.\nExample:\ntitle: \"Cecil in english\"\nlanguages:\n - code: en\n name: English\n locale: en_US\n - code: fr\n name: Fran\u00e7ais\n locale: fr_FR\n config:\n title: \"Cecil en fran\u00e7ais\"\nIn templates you can access to an option with {{ site.<option> }}, for example {{ site.title }}.\nIf an option is not available in the current language (e.g.: fr) it fallback to the global one (e.g.: en).", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#languages", "experimental": "0" }, { "objectID": "documentation/configuration#metatags", "page": "Configuration", "title": "metatags", "description": "metatags are SEO and social helpers that can be automatically injected in the <head>, with the partial template metatags.html.twig.", "content": "metatags are SEO and social helpers that can be automatically injected in the <head>, with the partial template metatags.html.twig.\nExample:\n<html lang=\"{{ site.language }}\">\n <head>\n <meta charset=\"utf-8\">\n {{ include('partials\/metatags.html.twig') }}\n <\/head>\n <body>\n ...\n <\/body>\n<\/html>\nThis template adds the following meta tags:\n\nPage title + Site title, or Site title + Site baseline\nPage\/Site description\nPage\/Site keywords\nPage\/Site author\nSearch engine crawler directives (robots)\nFavicon links\nNavigation links (first, previous, next, last)\nCanonical URL\nAlternate links (i.e.: RSS feed, others languages)\nrel=me links\nOpen Graph\nFacebook profile ID\nTwitter\/X Card\nFediverse tag\nStructured data (JSON-LD)\n\nmetatags options\nCecil uses page front matter to feed meta tags, and falls back to site options when needed.\ntitle: \"Page\/Site title\" # used by title meta\ndescription: \"Page\/Site description\" # used by description meta\ntags: [tag1, tag2] # used by keywords meta\nkeywords: [keyword1, keyword2] # obsolete\nauthor: # used by author meta\n name: <name> # author name\n url: <url> # author URL\n email: <email> # author email\nimage: image.jpg # used by Open Graph and social networks cards\ncanonical: # used to override the generated canonical URL\n url: <URL> # absolute URL\n title: \"<URL title>\" # optional canonical title\nsocial: # used by social networks meta\n twitter: # used by Twitter\/X Card\n url: <URL> # used for `rel=me` link\n site: username # site username\n creator: username # page author username\n mastodon: # used by Mastodon meta\n url: <URL> # used for `rel=me` link\n creator: handle # page author account\n facebook: # used by Facebook meta\n url: <URL> # used for `rel=me` link\n id: 123456789 # Facebook profile ID\n username: username # page author username\nIf needed, title and image can be overridden:\n{{ include('partials\/metatags.html.twig', {title: 'Custom title', image: og_image}) }}\nmetatags configuration\nmetatags:\n title: # title options\n divider: \" &middot; \" # string between page title and site title\n only: false # displays page title only (`false` by default)\n pagination: # pagination options\n shownumber: true # displays page number in title (`true` by default)\n label: \"Page %s\" # how to display page number (`Page %s` by default)\n robots: \"index,follow\" # web crawlers directives (`index,follow` by default)\n favicon: # favicon options\n enabled: true # includes favicon (`true` by default)\n image: favicon.png # path to favicon image\n sizes: # sizes by device\n - \"icon\": [32, 57, 76, 96, 128, 192, 228] # web browsers\n - \"shortcut icon\": [196] # Android\n - \"apple-touch-icon\": [120, 152, 180] # iOS\n navigation: true # includes previous and next links (`true` by default)\n image: true # includes image (`true` by default)\n og: true # includes Open Graph meta tags (`true` by default)\n articles: \"blog\" # articles' section (`blog` by default)\n twitter: true # includes Twitter\/X Card meta tags (`true` by default)\n mastodon: true # includes Mastodon meta tags (`true` by default)\n data: false # includes JSON-LD structured data (`false` by default)", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#metatags", "experimental": "0" }, { "objectID": "documentation/configuration#debug", "page": "Configuration", "title": "debug", "description": "Enables the debug mode, used to display debug information like very verbose logs, Twig dump, Twig profiler, SCSS sourcemap, etc.", "content": "Enables the debug mode, used to display debug information like very verbose logs, Twig dump, Twig profiler, SCSS sourcemap, etc.\ndebug: true\nThere are two other ways to enable debug mode:\n\nRun a command with the -vvv option\nSet the CECIL_DEBUG environment variable to true\n\n\nPages", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#debug", "experimental": "0" }, { "objectID": "documentation/configuration#pages-dir", "page": "Configuration", "title": "pages.dir", "description": "Directory source of pages (pages by default).", "content": "Directory source of pages (pages by default).\npages:\n dir: pages", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-dir", "experimental": "0" }, { "objectID": "documentation/configuration#pages-ext", "page": "Configuration", "title": "pages.ext", "description": "Extensions of pages files.", "content": "Extensions of pages files.\npages:\n ext: [md, markdown, mdown, mkdn, mkd, text, txt]", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-ext", "experimental": "0" }, { "objectID": "documentation/configuration#pages-exclude", "page": "Configuration", "title": "pages.exclude", "description": "Directories, paths and files name to exclude (accepts globs, strings and regexes).", "content": "Directories, paths and files name to exclude (accepts globs, strings and regexes).\npages:\n exclude: ['vendor', 'node_modules', '*.scss', '\/\\.bck$\/']", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-exclude", "experimental": "0" }, { "objectID": "documentation/configuration#pages-prefix-separator", "page": "Configuration", "title": "pages.prefix.separator", "description": "List of characters used as separator between a filename prefix (date or weight) and the slug.", "content": "List of characters used as separator between a filename prefix (date or weight) and the slug.\npages:\n prefix:\n separator: ['-', '_']", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-prefix-separator", "experimental": "0" }, { "objectID": "documentation/configuration#pages-sortby", "page": "Configuration", "title": "pages.sortby", "description": "Default collections sort method.", "content": "Default collections sort method.\npages:\n sortby: date # `date`, `updated`, `title` or `weight`\n # or\n sortby:\n variable: date # `date`, `updated`, `title` or `weight`\n desc_title: false # sort by title in descending order\n reverse: false # reverse the sort order", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-sortby", "experimental": "0" }, { "objectID": "documentation/configuration#pages-pagination", "page": "Configuration", "title": "pages.pagination", "description": "Pagination is available for list pages (type is homepage, section or term).", "content": "Pagination is available for list pages (type is homepage, section or term).\npages:\n pagination:\n max: 5 # maximum number of entries per page\n path: page # path to the paginated page\nDisable pagination\nPagination can be disabled:\npages:\n pagination: false", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-pagination", "experimental": "0" }, { "objectID": "documentation/configuration#pages-paths", "page": "Configuration", "title": "pages.paths", "description": "Apply a custom path for all pages of a Section.", "content": "Apply a custom path for all pages of a Section.\npages:\n paths:\n - section: <section\u2019s ID>\n path: <path of pages>\nPath placeholders\n\n:year\n:month\n:day\n:section\n:slug\n\nExample:\npages:\n paths:\n - section: Blog\n path: :section\/:year\/:month\/:day\/:slug # e.g.: \/blog\/2020\/12\/01\/my-post\/\n# localized\nlanguages:\n - code: fr\n name: Fran\u00e7ais\n locale: fr_FR\n config:\n pages:\n paths:\n - section: Blog\n path: blogue\/:year\/:month\/:day\/:slug # e.g.: \/blogue\/2020\/12\/01\/mon-billet\/", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-paths", "experimental": "0" }, { "objectID": "documentation/configuration#pages-frontmatter", "page": "Configuration", "title": "pages.frontmatter", "description": "Page front matter format (yaml by default, also accepts ini, toml and json).", "content": "Page front matter format (yaml by default, also accepts ini, toml and json).\npages:\n frontmatter: yaml", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-frontmatter", "experimental": "0" }, { "objectID": "documentation/configuration#pages-body", "page": "Configuration", "title": "pages.body", "description": "Page body options.", "content": "Page body options.\nTo know how those options impacts your content see Content > Markdown documentation.\npages.body.toc\nHeaders used to build the table of contents ([h2, h3] by default).\npages:\n body:\n toc: [h2, h3]\npages.body.highlight\nEnables code syntax highlighting (false by default).\npages:\n body:\n highlight: false\npages.body.images\nImages handling options.\npages:\n body:\n images:\n formats: [] # adds alternative image formats as `source` (e.g. `[avif, webp]`, empty array by default)\n resize: 0 # resizes all images to <width> (in pixels, `0` to disable)\n responsive: false # adds responsive image variants to the `srcset` attribute (`false` by default)\n lazy: true # adds `loading=\"lazy\"` attribute (`true` by default)\n decoding: true # adds `decoding=\"async\"` attribute (`true` by default)\n caption: false # puts the image in a <figure> element and adds a <figcaption> containing the title (`false` by default)\n placeholder: '' # fills the <img> background before loading ('color' or 'lqip', empty by default)\n class: '' # sets a default class on each image (empty by default)\n remote: # remote image handling (set to `false` to disable)\n fallback: # path to the fallback image, stored in assets dir (empty by default)\nSince version 8.41.0, the pages.body.images.resize option is used to resize images to a specific width, no more to enable the resize feature (enabled systematically).\nGlobal options, like responsives images widths and sizes, are configurable in the assets.images section.\nRemote images are downloaded and converted into Assets to be manipulated. You can disable this behavior by setting the option pages.body.images.remote.enabled to false.\npages.body.links\nLinks handling options.\npages:\n body:\n links:\n embed:\n enabled: false # turns links in embedded content if possible (`false` by default)\n video: [mp4, webm] # video files extensions\n audio: [mp3] # audio files extensions\n external:\n blank: false # if true open external link in new tab\n noopener: true # if true add \"noopener\" to `rel` attribute\n noreferrer: true # if true add \"noreferrer\" to `rel` attribute\n nofollow: false # if true add \"nofollow\" to `rel` attribute\npages.body.excerpt\nExcerpt handling options.\npages:\n body:\n excerpt:\n separator: excerpt|break # string to use as separator (`excerpt|break` by default)\n capture: before # part to capture, `before` or `after` the separator (`before` by default)", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-body", "experimental": "0" }, { "objectID": "documentation/configuration#pages-virtual", "page": "Configuration", "title": "pages.virtual", "description": "Virtual pages is the best way to create pages without content (front matter only).", "content": "Virtual pages is the best way to create pages without content (front matter only).\nIt consists of a list of pages with a path and some front matter variables.\nExample:\npages:\n virtual:\n - path: code\n redirect: https:\/\/github.com\/ArnaudLigny", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-virtual", "experimental": "0" }, { "objectID": "documentation/configuration#pages-default", "page": "Configuration", "title": "pages.default", "description": "Default pages are pages created automatically by Cecil (from built-in templates):", "content": "Default pages are pages created automatically by Cecil (from built-in templates):\npages:\n default:\n index:\n path: ''\n title: Home\n published: true\n 404:\n path: 404\n title: Page not found\n layout: 404\n uglyurl: true\n published: true\n excluded: true\n robots:\n path: robots\n title: Robots.txt\n layout: robots\n output: txt\n published: true\n excluded: true\n multilingual: false\n sitemap:\n path: sitemap\n title: XML sitemap\n layout: sitemap\n output: xml\n changefreq: monthly\n priority: 0.5\n published: true\n excluded: true\n multilingual: false\n xsl\/atom:\n path: xsl\/atom\n layout: feed\n output: xsl\n uglyurl: true\n published: true\n excluded: true\n xsl\/rss:\n path: xsl\/rss\n layout: feed\n output: xsl\n uglyurl: true\n published: false\n excluded: true\nThe structure is almost identical of pages.virtual, except the named key.\nEach one can be:\n\ndisabled: published: false\nexcluded from list pages: excluded: true\nexcluded from localization: multilingual: false\n\nSince version 8.68.0 you can override the default robots.txt page by creating a page with the same path:\npages\/robots.md\n---\nlayout: robots\noutput: txt\n---\nUser-agent: AI-bot\nDisallow: \/", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-default", "experimental": "0" }, { "objectID": "documentation/configuration#pages-generators", "page": "Configuration", "title": "pages.generators", "description": "Generators are used by Cecil to create additional pages (e.g.: sitemap, feed, pagination, etc.) from existing pages, or from other sources like the configuration file or external sources.", "content": "Generators are used by Cecil to create additional pages (e.g.: sitemap, feed, pagination, etc.) from existing pages, or from other sources like the configuration file or external sources.\nBelow the list of Generators provided by Cecil, in a defined order:\npages:\n generators:\n 10: 'Cecil\\Generator\\DefaultPages'\n 20: 'Cecil\\Generator\\VirtualPages'\n 30: 'Cecil\\Generator\\ExternalBody'\n 40: 'Cecil\\Generator\\Section'\n 50: 'Cecil\\Generator\\Taxonomy'\n 60: 'Cecil\\Generator\\Homepage'\n 70: 'Cecil\\Generator\\Pagination'\n 80: 'Cecil\\Generator\\Alias'\n 90: 'Cecil\\Generator\\Redirect'\nYou can extend Cecil with Pages generator.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-generators", "experimental": "0" }, { "objectID": "documentation/configuration#pages-subsets", "page": "Configuration", "title": "pages.subsets", "description": "Subsets are used to render a part of the pages collection, based on a specific path, language or output format, with the command:", "content": "Subsets are used to render a part of the pages collection, based on a specific path, language or output format, with the command:\ncecil build --render-subset=<name>\npages:\n subsets:\n <name>:\n path: <path> # glob or string path (e.g.: `blog\/*`, `blog`)\n language: <language> # language code (e.g.: `en`, `fr`)\n output: <output> # output format (e.g.: `html`, `atom`)\nExample:\npages:\n subsets:\n blog_en:\n path: blog\n language: en\n output: html\n search_index:\n path: '*'\n output: json\n\nData\nWhere data files are stored and what extensions are handled.\nSupported formats: YAML, JSON, XML and CSV.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#pages-subsets", "experimental": "0" }, { "objectID": "documentation/configuration#data-dir", "page": "Configuration", "title": "data.dir", "description": "Data source directory (data by default).", "content": "Data source directory (data by default).\ndata:\n dir: data", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#data-dir", "experimental": "0" }, { "objectID": "documentation/configuration#data-ext", "page": "Configuration", "title": "data.ext", "description": "Array of files extensions.", "content": "Array of files extensions.\ndata:\n ext: [yaml, yml, json, xml, csv]", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#data-ext", "experimental": "0" }, { "objectID": "documentation/configuration#data-load", "page": "Configuration", "title": "data.load", "description": "Enables site.data collection (true by default).", "content": "Enables site.data collection (true by default).\ndata:\n load: true\n\nStatic\nManagement of static files are copied (PDF, fonts, etc.).\nYou should put your assets files, used by asset(), in the assets directory to avoid unnecessary files copy.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#data-load", "experimental": "0" }, { "objectID": "documentation/configuration#static-dir", "page": "Configuration", "title": "static.dir", "description": "Static files source directory (static by default).", "content": "Static files source directory (static by default).\nstatic:\n dir: static", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#static-dir", "experimental": "0" }, { "objectID": "documentation/configuration#static-target", "page": "Configuration", "title": "static.target", "description": "Directory where static files are copied (root by default).", "content": "Directory where static files are copied (root by default).\nstatic:\n target: ''", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#static-target", "experimental": "0" }, { "objectID": "documentation/configuration#static-exclude", "page": "Configuration", "title": "static.exclude", "description": "List of excluded files. Accepts globs, strings and regexes.", "content": "List of excluded files. Accepts globs, strings and regexes.\nstatic:\n exclude: ['sass', 'scss', '*.scss', 'package*.json', 'node_modules']\nIf you use Bootstrap Icons you can exclude the node_modules except node_modules\/bootstrap-icons with a regular expression:\nexclude: ['sass', 'scss', '*.scss', 'package*.json', '#node_modules\/(?!bootstrap-icons)#']", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#static-exclude", "experimental": "0" }, { "objectID": "documentation/configuration#static-load", "page": "Configuration", "title": "static.load", "description": "Enables site.static collection (false by default).", "content": "Enables site.static collection (false by default).\nstatic:\n load: false", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#static-load", "experimental": "0" }, { "objectID": "documentation/configuration#static-mounts", "page": "Configuration", "title": "static.mounts", "description": "Allows to copy specific files or directories to a specific destination.", "content": "Allows to copy specific files or directories to a specific destination.\nstatic:\n mounts: []", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#static-mounts", "experimental": "0" }, { "objectID": "documentation/configuration#static-example", "page": "Configuration", "title": "static example", "description": "", "content": "static:\n dir: docs\n target: docs\n exclude: ['sass', '*.scss', '\/\\.bck$\/']\n load: true\n mounts:\n - source\/path\/file.ext: dest\/path\/file.ext\n - node_modules\/bootstrap-icons\/font\/fonts: fonts\nAssets\nAssets management (images, CSS and JS files).", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#static-example", "experimental": "0" }, { "objectID": "documentation/configuration#assets-dir", "page": "Configuration", "title": "assets.dir", "description": "Assets source directory (assets by default).", "content": "Assets source directory (assets by default).\nassets:\n dir: assets", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#assets-dir", "experimental": "0" }, { "objectID": "documentation/configuration#assets-target", "page": "Configuration", "title": "assets.target", "description": "Directory where remote and resized assets files are saved (root by default).", "content": "Directory where remote and resized assets files are saved (root by default).\nassets:\n target: ''", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#assets-target", "experimental": "0" }, { "objectID": "documentation/configuration#assets-fingerprint", "page": "Configuration", "title": "assets.fingerprint", "description": "Enables fingerprinting (cache busting) for assets files (true by default).", "content": "Enables fingerprinting (cache busting) for assets files (true by default).\nassets:\n fingerprint: true", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#assets-fingerprint", "experimental": "0" }, { "objectID": "documentation/configuration#assets-compile", "page": "Configuration", "title": "assets.compile", "description": "Enables Sass files compilation (true by default). See the documentation of scssphp for options details.", "content": "Enables Sass files compilation (true by default). See the documentation of scssphp for options details.\nassets:\n compile:\n style: expanded # compilation style (`expanded` or `compressed`. `expanded` by default)\n import: [sass, scss] # list of imported paths (`[sass, scss, node_modules]` by default)\n sourcemap: false # enables sourcemap in debug mode (`false` by default)\n variables: [] # list of preset variables (empty by default)\nsourcemap is used to debug SCSS compilation (debug mode must be enabled).", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#assets-compile", "experimental": "0" }, { "objectID": "documentation/configuration#assets-minify", "page": "Configuration", "title": "assets.minify", "description": "Enables CSS and JS minification (true by default).", "content": "Enables CSS and JS minification (true by default).\nassets:\n minify: true", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#assets-minify", "experimental": "0" }, { "objectID": "documentation/configuration#assets-images", "page": "Configuration", "title": "assets.images", "description": "Images management.", "content": "Images management.\nassets:\n images:\n optimize: false # enables images optimization with JpegOptim, Optipng, Pngquant 2, SVGO 1, Gifsicle, cwebp, avifenc (`false` by default)\n quality: 75 # image quality of `optimize` and `resize` (`75` by default)\n responsive:\n widths: [480, 640, 768, 1024, 1366, 1600, 1920] # `srcset` attribute images widths\n sizes:\n default: '100vw' # default `sizes` attribute (`100vw` by default)", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#assets-images", "experimental": "0" }, { "objectID": "documentation/configuration#assets-images-cdn", "page": "Configuration", "title": "assets.images.cdn", "description": "URL of image assets can be easily replaced by a provided CDN url.", "content": "URL of image assets can be easily replaced by a provided CDN url.\nassets:\n images:\n cdn:\n enabled: false # enables Image CDN (`false` by default)\n canonical: true # `image_url` is canonical (instead of a relative path) (`true` by default)\n remote: true # handles not local images too (`true` by default)\n account: 'xxxx' # provider account\n url: 'https:\/\/provider.tld\/%account%\/%image_url%?w=%width%&q=%quality%&format=%format%'\nurl is a pattern that contains variables:\n\n%account% replaced by the assets.images.cdn.account option\n%image_url% replaced by the image canonical URL or path\n%width% replaced by the image width\n%quality% replaced by the assets.images.quality option\n%format% replaced by the image format\n\nSee CDN providers.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#assets-images-cdn", "experimental": "0" }, { "objectID": "documentation/configuration#assets-remote-useragent", "page": "Configuration", "title": "assets.remote.useragent", "description": "User agent used to download remote assets.", "content": "User agent used to download remote assets.\nassets:\n remote:\n useragent:\n default: <string> # default user agent\n useragent1: <string>\n useragent2: <string>\nLayouts\nTemplates options.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#assets-remote-useragent", "experimental": "0" }, { "objectID": "documentation/configuration#layouts-dir", "page": "Configuration", "title": "layouts.dir", "description": "Templates directory source (layouts by default).", "content": "Templates directory source (layouts by default).\nlayouts:\n dir: layouts", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#layouts-dir", "experimental": "0" }, { "objectID": "documentation/configuration#layouts-images", "page": "Configuration", "title": "layouts.images", "description": "Images handling options.", "content": "Images handling options.\nlayouts:\n images:\n formats: [] # used by `html` function: adds alternatives image formats as `source` (e.g. `[avif, webp]`, empty array by default)\n responsive: false # used by `html` function: adds responsive images ('width' or 'density', `false` by default)", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#layouts-images", "experimental": "0" }, { "objectID": "documentation/configuration#layouts-translations", "page": "Configuration", "title": "layouts.translations", "description": "Translations handling options.", "content": "Translations handling options.\nlayouts:\n translations:\n dir: translations # translations source directory (`translations` by default)\n formats: ['yaml', 'mo'] # translations files format (`yaml` and `mo` by default)", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#layouts-translations", "experimental": "0" }, { "objectID": "documentation/configuration#layouts-components", "page": "Configuration", "title": "layouts.components", "description": "Templates Components options.", "content": "Templates Components options.\nlayouts:\n components:\n dir: components # components source directory (`components` by default)\n ext: twig # components files extension (`twig` by default)\n\nOutput\nDefines where and in what format pages are rendered.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#layouts-components", "experimental": "0" }, { "objectID": "documentation/configuration#output-dir", "page": "Configuration", "title": "output.dir", "description": "Directory where rendered pages\u2019 files are saved (_site by default).", "content": "Directory where rendered pages\u2019 files are saved (_site by default).\noutput:\n dir: _site", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#output-dir", "experimental": "0" }, { "objectID": "documentation/configuration#output-formats", "page": "Configuration", "title": "output.formats", "description": "List of output formats definition, which are used to render pages (e.g. HTML, Atom, RSS, JSON, XML, etc.).", "content": "List of output formats definition, which are used to render pages (e.g. HTML, Atom, RSS, JSON, XML, etc.).\noutput:\n formats:\n - name: <name> # name of the format, e.g.: `html` (required)\n mediatype: <media type> # media type (MIME type), ie: 'text\/html' (optional)\n subpath: <sub path> # sub path, e.g.: `amp` in `path\/amp\/index.html` (optional)\n filename: <file name> # file name, e.g.: `index` in `path\/index.html` (optional)\n extension: <extension> # file extension, e.g.: `html` in `path\/index.html` (required)\n exclude: [<variable>] # don\u2019t apply this format to pages identified by listed variables, e.g.: `[redirect, paginated]` (optional)\nThose formats are used in the output.pagetypeformats configuration and in the output page variable.\nDefault formats\nCecil provides some default formats, which can be overridden in the configuration file: html (default), atom, rss, json, xml, txt, amp, js, webmanifest, xsl, jsonfeed, iframe, oembed.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#output-formats", "experimental": "0" }, { "objectID": "documentation/configuration#output-pagetypeformats", "page": "Configuration", "title": "output.pagetypeformats", "description": "It\u2019s not required to set output variable for each page, as Cecil automatically applies the formats defined for each page type (homepage, page, section, vocabulary and term).", "content": "It\u2019s not required to set output variable for each page, as Cecil automatically applies the formats defined for each page type (homepage, page, section, vocabulary and term).\noutput:\n pagetypeformats:\n page: [<format>]\n homepage: [<format>]\n section: [<format>]\n vocabulary: [<format>]\n term: [<format>]\nSeveral formats can be defined for the one type of page. For example the section page type can be automatically rendered in HTML and Atom:\noutput:\n pagetypeformats:\n section: [html, atom]\nTo render a page, Cecil lookup for a template named <layout>.<format>.twig (e.g. page.html.twig)", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#output-pagetypeformats", "experimental": "0" }, { "objectID": "documentation/configuration#output-example", "page": "Configuration", "title": "output example", "description": "", "content": "output:\n dir: _site\n formats:\n - name: html\n mediatype: text\/html\n filename: index\n extension: html\n - name: atom\n mediatype: application\/xml\n filename: atom\n extension: xml\n exclude: [redirect, paginated]\n pagetypeformats:\n page: [html]\n homepage: [html, atom]\n section: [html, atom]\n vocabulary: [html]\n term: [html, atom]", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#output-example", "experimental": "0" }, { "objectID": "documentation/configuration#post-process", "page": "Configuration", "title": "Post process", "description": "You can extend Cecil capabilities with an Output post processor to modify the output files after they have been generated.", "content": "You can extend Cecil capabilities with an Output post processor to modify the output files after they have been generated.\n\nCache\nCache options.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#post-process", "experimental": "0" }, { "objectID": "documentation/configuration#cache-enabled", "page": "Configuration", "title": "cache.enabled", "description": "Cache is enabled by default (true), but you can disable it with:", "content": "Cache is enabled by default (true), but you can disable it with:\ncache:\n enabled: false\nIt\u2019s not recommended to disable the cache for performance reasons.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#cache-enabled", "experimental": "0" }, { "objectID": "documentation/configuration#cache-dir", "page": "Configuration", "title": "cache.dir", "description": "Directory where cache files are stored (.cache by default).", "content": "Directory where cache files are stored (.cache by default).\ncache:\n dir: '.cache'\nThe cache directory is relative to the site directory, but you can use an absolute path: it can be useful to store the cache in a shared directory.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#cache-dir", "experimental": "0" }, { "objectID": "documentation/configuration#cache-assets", "page": "Configuration", "title": "cache.assets", "description": "Assets cache options.", "content": "Assets cache options.\ncache.assets.ttl\nTime to live of assets cache in seconds (null by default = no expiration).\ncache:\n assets:\n ttl: ~\ncache.assets.remote.ttl\nTime to live of remote assets cache in seconds (7 days by default).\ncache:\n assets:\n remotes:\n ttl: 604800 # 7 days", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#cache-assets", "experimental": "0" }, { "objectID": "documentation/configuration#cache-templates", "page": "Configuration", "title": "cache.templates", "description": "Disables templates cache with false (true by default).", "content": "Disables templates cache with false (true by default).\ncache:\n templates: true\nSee templates cache documentation for more details.", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#cache-templates", "experimental": "0" }, { "objectID": "documentation/configuration#cache-translations", "page": "Configuration", "title": "cache.translations", "description": "Disables translations cache with false (true by default).", "content": "Disables translations cache with false (true by default).\ncache:\n translations: true\n\nServer", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#cache-translations", "experimental": "0" }, { "objectID": "documentation/configuration#server-headers", "page": "Configuration", "title": "server.headers", "description": "You can define custom HTTP headers, used by the local preview server.", "content": "You can define custom HTTP headers, used by the local preview server.\nSince version 8.38.0, the headers option has been moved to the server.headers section.\nserver:\n headers:\n - path: <path> # Relative path, prefixed with a slash. Support \"*\" wildcard.\n headers:\n - key: <key>\n value: \"<value>\"\nIt's useful to test custom Content Security Policy or Cache-Control.\nExample:\nserver:\n headers:\n - path: \/*\n headers:\n - key: X-Frame-Options\n value: \"SAMEORIGIN\"\n - key: X-XSS-Protection\n value: \"1; mode=block\"\n - key: X-Content-Type-Options\n value: \"nosniff\"\n - key: Content-Security-Policy\n value: \"default-src 'self'; object-src 'self'; img-src 'self'\"\n - key: Strict-Transport-Security\n value: \"max-age=31536000; includeSubDomains; preload\"\n - path: \/assets\/*\n headers:\n - key: Cache-Control\n value: \"public, max-age=31536000\"\n - path: \/foo.html\n headers:\n - key: Foo\n value: \"bar\"\n\nOptimize\nThe optimization options allow to enable compression of output files: HTML, CSS, JavaScript and image.\noptimize:\n enabled: false # enables files optimization (`false` by default)\n html:\n enabled: true # enables HTML files optimization\n ext: [html, htm] # supported files extensions\n css:\n enabled: true # enables CSS files optimization\n ext: [css] # supported files extensions\n js:\n enabled: true # enables JavaScript files optimization\n ext: [js] # supported files extensions\n images:\n enabled: true # enables images files optimization\n ext: [jpeg, jpg, png, gif, webp, svg, avif] # supported files extensions\nThis option is disabled by default and can be enabled via:\noptimize: true\nOnce the global option is enabled, the 4 file types will be processed.\nIt is possible to disable each of them via enabled: false and modify processed files extension via ext.\nIt is also possible to enable this option through CLI when using the \"build\" and \"serve\" commands via the --optimize option.\nImages compressor will use these binaries if they are present in the system: JpegOptim, Optipng, Pngquant 2, SVGO, Gifsicle, cwebp and avifenc.\n\nOverride configuration", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#server-headers", "experimental": "0" }, { "objectID": "documentation/configuration#environment-variables", "page": "Configuration", "title": "Environment variables", "description": "The configuration can be overridden through environment variables.", "content": "The configuration can be overridden through environment variables.\nEach environment variable name must be prefixed with CECIL_ and the configuration key must be set in uppercase.\nFor example, the following command set the website\u2019s baseurl:\nexport CECIL_BASEURL=\"https:\/\/example.com\/\"", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#environment-variables", "experimental": "0" }, { "objectID": "documentation/configuration#cli-option", "page": "Configuration", "title": "CLI option", "description": "You can combine multiple configuration files, with the --config option (left-to-right precedence):", "content": "You can combine multiple configuration files, with the --config option (left-to-right precedence):\nphp cecil.phar --config config-1.yml,config-2.yml", "date": "2021-05-07T00:00:00+00:00", "href": "documentation/configuration/#cli-option", "experimental": "0" }, { "objectID": "documentation/configuration/cdn-providers#run-locally", "page": "CDN providers", "title": "Run locally", "description": "", "content": "Setup Netlify CLI\nnpm install netlify-cli -g\nnetlify link\nnetlify.toml:\n[dev]\n targetPort = 8000\nRun local server\nphp cecil.phar serve & netlify dev\nOpen http:\/\/localhost:8888", "date": "2023-10-23T00:00:00+00:00", "href": "documentation/configuration/cdn-providers/#run-locally", "experimental": "0" }, { "objectID": "documentation/commands#pages-models", "page": "Commands", "title": "Page’s models", "description": "You can define your own models for your new pages in the models directory:", "content": "You can define your own models for your new pages in the models directory:\n\nThe name must be based on the section\u2019s name (e.g.: blog.md)\nThe default model must be named default.md (for root pages or pages\u2019s section without model)\n\nTwo dynamic variables are available:\n\n%title%: the file\u2019s name\n%date%: the current date", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/commands/#pages-models", "experimental": "0" }, { "objectID": "documentation/commands#open-with-your-editor", "page": "Commands", "title": "Open with your editor", "description": "With the --open option, the editor will be opened automatically. So use editor key in your configuration file to define the default editor (e.g.: editor: typora).", "content": "With the --open option, the editor will be opened automatically. So use editor key in your configuration file to define the default editor (e.g.: editor: typora).\nbuild\nBuilds the site.\nDescription:\n Builds the website\n\nUsage:\n build [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -d, --drafts Include drafts\n -u, --baseurl=BASEURL Set the base URL\n -o, --output=OUTPUT Set the output directory\n --optimize|--no-optimize Enable (or disable --no-optimize) optimization of generated files\n --dry-run Build without saving\n -c, --config=CONFIG Set the path to extra config files (comma-separated)\n --clear-cache[=CLEAR-CACHE] Clear cache before build (optional cache key as regular expression) [default: false]\n -p, --page=PAGE Build a specific page\n --render-subset=RENDER-SUBSET Render a subset of pages\n --show-pages Show list of built pages in a table\n -m, --metrics Show build metrics (duration and memory) of each step\n --notif Send desktop notification on build completion\n -h, --help Display help for the given command. When no command is given display help for the list command\n -q, --quiet Do not output any message\n -V, --version Display this application version\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nHelp:\n The build command generates the website in the output directory.\n\n cecil.phar build\n cecil.phar build path\/to\/the\/working\/directory\n cecil.phar build --baseurl=https:\/\/example.com\/\n cecil.phar build --output=_site\n\n To build the website with optimization of generated files, you can use the --optimize option.\n This is useful to reduce the size of the generated files and improve performance:\n\n cecil.phar build --optimize\n cecil.phar build --no-optimize\n\n To build the website without overwriting files in the output directory, you can use the --dry-run option.\n This is useful to check what would be built without actually writing files:\n\n cecil.phar build --dry-run\n\n To build the website with a specific subset of rendered pages, you can use the --render-subset option.\n This is useful to build only a part of the website, for example, only \"hot\" pages or a specific section:\n\n cecil.phar build --render-subset=subset\n\n To show build steps metrics, run:\n\n cecil.phar build --metrics\nserve\nBuilds and serves the site locally.\nThe web server is designed to aid website testing. It is not intended to be a full-featured web server and it should not be used on a public network.\nDescription:\n Starts the built-in server\n\nUsage:\n serve [options] [--] [<path>]\n\nArguments:\n path Use the given path as working directory\n\nOptions:\n -o, --open Open web browser automatically\n --host=HOST Server host [default: \"localhost\"]\n --port=PORT Server port [default: \"8000\"]\n -w, --watch|--no-watch Enable (or disable --no-watch) changes watcher (enabled by default)\n -d, --drafts Include drafts\n --optimize|--no-optimize Enable (or disable --no-optimize) optimization of generated files\n -c, --config=CONFIG Set the path to extra config files (comma-separated)\n --clear-cache[=CLEAR-CACHE] Clear cache before build (optional cache key as regular expression) [default: false]\n -p, --page=PAGE Build a specific page\n --no-ignore-vcs Changes watcher must not ignore VCS directories\n -m, --metrics Show build metrics (duration and memory) of each step\n --timeout=TIMEOUT Sets the process timeout (max. runtime) in seconds [default: 7200]\n --notif Send desktop notification on server start\n -h, --help Display help for the given command. When no command is given display help for the list command\n -q, --quiet Do not output any message\n -V, --version Display this application version\n --ansi|--no-ansi Force (or disable --no-ansi) ANSI output\n -n, --no-interaction Do not ask any interactive question\n -v|vv|vvv, --verbose Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug\n\nHelp:\n The serve command starts the live-reloading-built-in web server.\n\n cecil.phar serve\n cecil.phar serve path\/to\/the\/working\/directory\n cecil.phar serve --open\n cecil.phar serve --drafts\n cecil.phar serve --no-watch\n\n You can use a custom host and port by using the --host and --port options:\n\n cecil.phar serve --host=127.0.0.1 --port=8080\n\n To build the website with an extra configuration file, you can use the --config option.\n This is useful during local development to override some settings without modifying the main configuration:\n\n cecil.phar serve --config=config\/dev.yml\n\n To start the server with changes watcher not ignoring VCS directories, run:\n\n cecil.phar serve --no-ignore-vcs\n\n To define the process timeout (in seconds), run:\n\n cecil.phar serve --timeout=7200", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/commands/#open-with-your-editor", "experimental": "0" }, { "objectID": "documentation/deploy#netlify", "page": "Deploy", "title": "Netlify", "description": "", "content": "A powerful serverless platform with an intuitive git-based workflow. Automated deployments, shareable previews, and much more.\n\n\u27a1\ufe0f https:\/\/www.netlify.com\nnetlify.toml:\n[build]\n publish = \"_site\"\n command = \"curl -sSOL https:\/\/cecil.app\/build.sh && bash .\/build.sh\"\n\n[context.production.environment]\n CECIL_ENV = \"production\"\n\n[context.deploy-preview.environment]\n CECIL_ENV = \"preview\"\nOfficial documentation", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/deploy/#netlify", "experimental": "0" }, { "objectID": "documentation/deploy#vercel", "page": "Deploy", "title": "Vercel", "description": "", "content": "Vercel combines the best developer experience with an obsessive focus on end-user performance.\n\n\u27a1\ufe0f https:\/\/vercel.com\nvercel.json:\n{\n \"buildCommand\": \"curl -sSOL https:\/\/cecil.app\/build.sh && bash .\/build.sh\",\n \"outputDirectory\": \"_site\"\n}\nOfficial documentation", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/deploy/#vercel", "experimental": "0" }, { "objectID": "documentation/deploy#statichost", "page": "Deploy", "title": "statichost", "description": "", "content": "Modern static site hosting with European servers and absolutely no personal data collection!\n\n\u27a1\ufe0f https:\/\/statichost.eu\nstatichost.yml:\nimage: wordpress:cli-php8.4\ncommand: curl -sSOL https:\/\/cecil.app\/build.sh && bash .\/build.sh\npublic: _site\nOfficial documentation", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/deploy/#statichost", "experimental": "0" }, { "objectID": "documentation/deploy#cloudflare-pages", "page": "Deploy", "title": "Cloudflare Pages", "description": "", "content": "Cloudflare Pages no longer supports PHP.\n\nCloudflare Pages is a JAMstack platform for frontend developers to collaborate and deploy websites.\n\n\u27a1\ufe0f https:\/\/pages.cloudflare.com\nBuild configurations:\n\nFramework preset: None\nBuild command: curl -sSOL https:\/\/cecil.app\/build.sh && bash .\/build.sh\nBuild output directory: _site\n\nOfficial documentation", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/deploy/#cloudflare-pages", "experimental": "0" }, { "objectID": "documentation/deploy#render", "page": "Deploy", "title": "Render", "description": "", "content": "Render no longer supports PHP.\n\nRender is a unified cloud to build and run all your apps and websites with free TLS certificates, global CDN, private networks and auto deploys from Git.\n\n\u27a1\ufe0f https:\/\/render.com\nrender.yaml:\npreviewsEnabled: true\nservices:\n - type: web\n name: Cecil\n env: static\n buildCommand: curl -sSOL https:\/\/cecil.app\/build.sh && bash .\/build.sh\n staticPublishPath: _site\n pullRequestPreviewsEnabled: true\nOfficial documentation\nContinuous build & deploy", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/deploy/#render", "experimental": "0" }, { "objectID": "documentation/deploy#github-pages", "page": "Deploy", "title": "GitHub Pages", "description": "", "content": "Websites for you and your projects, hosted directly from your GitHub repository. Just edit, push, and your changes are live.\n\n\u27a1\ufe0f https:\/\/pages.github.com\n.github\/workflows\/build-and-deploy.yml:\nname: Build and deploy to GitHub Pages\n\non:\n push:\n branches: [master, main]\n workflow_dispatch:\n\nconcurrency:\n group: pages\n cancel-in-progress: true\n\njobs:\n build:\n runs-on: ubuntu-latest\n steps:\n - name: Checkout source\n uses: actions\/checkout@v4\n - name: Setup PHP\n uses: shivammathur\/setup-php@v2\n with:\n php-version: pre-installed\n extensions: mbstring, fileinfo, gd, imagick, intl, gettext\n - name: Restore Cecil cache\n uses: actions\/cache\/restore@v4\n with:\n path: .\/.cache\n key: cecil-cache-\n restore-keys: |\n cecil-cache-\n - name: Setup Pages\n id: pages\n uses: actions\/configure-pages@v5\n - name: Build with Cecil\n uses: Cecilapp\/Cecil-Action@v3\n with:\n args: '-v --baseurl=\"${{ steps.pages.outputs.base_url }}\/\"'\n - name: Save Cecil cache\n uses: actions\/cache\/save@v4\n with:\n path: .\/.cache\n key: cecil-cache-${{ hashFiles('.\/.cache\/**\/*') }}\n - name: Upload artifact\n uses: actions\/upload-pages-artifact@v3\n\n deploy:\n needs: build\n permissions:\n pages: write\n id-token: write\n environment:\n name: github-pages\n url: ${{ steps.deployment.outputs.page_url }}\n runs-on: ubuntu-latest\n steps:\n - name: Deploy to GitHub Pages\n id: deployment\n uses: actions\/deploy-pages@v4\nOfficial documentation", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/deploy/#github-pages", "experimental": "0" }, { "objectID": "documentation/deploy#gitlab-ci", "page": "Deploy", "title": "GitLab CI", "description": "", "content": "With GitLab Pages, you can publish static websites directly from a repository in GitLab.\n\n\u27a1\ufe0f https:\/\/about.gitlab.com\/solutions\/continuous-integration\/\n.gitlab-ci.yml:\nimage: wordpress:cli-php8.4\n\ntest:\n stage: test\n variables:\n CECIL_OUTPUT_DIR: test\n script:\n - curl -sSOL https:\/\/cecil.app\/build.sh && bash .\/build.sh\n artifacts:\n paths:\n - test\n except:\n - master\n\npages:\n stage: deploy\n variables:\n CECIL_ENV: production\n CECIL_OUTPUT_DIR: public\n script:\n - curl -sSOL https:\/\/cecil.app\/build.sh && bash .\/build.sh\n artifacts:\n paths:\n - public\n only:\n - master\n\ncache:\n paths:\n - composer-cache\/\n - vendor\/\n - .cache\/\nOfficial documentation\nStatic hosting", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/deploy/#gitlab-ci", "experimental": "0" }, { "objectID": "documentation/deploy#surge", "page": "Deploy", "title": "Surge", "description": "", "content": "Shipping web projects should be fast, easy, and low risk. Surge is static web publishing for Front-End Developers, right from the CLI.\n\n\u27a1\ufe0f https:\/\/surge.sh\nTerminal:\nnpm install -g surge\nsurge _site\/\nOfficial documentation", "date": "2020-12-19T00:00:00+00:00", "href": "documentation/deploy/#surge", "experimental": "0" }, { "objectID": "documentation/library#build", "page": "Library", "title": "Build", "description": "Build a new website with a custom configuration:", "content": "Build a new website with a custom configuration:\nuse Cecil\\Builder;\n\n\/\/ Create a configuration array\n$config = [\n 'title' => \"My website\",\n 'baseurl' => 'https:\/\/domain.tld\/',\n];\n\n\/\/ Build with the custom configuration\nBuilder::create($config)->build();\nThe main parameter of the create method should be a PHP array or a Cecil\\Config instance.", "date": "2023-12-13T00:00:00+00:00", "href": "documentation/library/#build", "experimental": "0" }, { "objectID": "documentation/library#example", "page": "Library", "title": "Example", "description": "", "content": "require_once 'vendor\/autoload.php';\n\nuse Cecil\\Builder;\n\n\/\/ Build with the website with the `config.php` configuration file\nCecil::create(require('config.php'))->build();\n\n\/\/ Preview locally\nexec('php -S localhost:8000 -t _site');", "date": "2023-12-13T00:00:00+00:00", "href": "documentation/library/#example", "experimental": "0" } ]