{"id":19614985,"url":"https://github.com/infostreams/snippets","last_synced_at":"2025-04-28T02:31:00.707Z","repository":{"id":24817771,"uuid":"28232160","full_name":"infostreams/snippets","owner":"infostreams","description":"A PhileCMS plugin to extend Markdown syntax - so you can easily add links, images, videos or other content to your page","archived":false,"fork":false,"pushed_at":"2017-09-05T08:29:33.000Z","size":26,"stargazers_count":5,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-05T05:11:23.172Z","etag":null,"topics":["kirbytext","philecms","php","snippets"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/infostreams.png","metadata":{"files":{"readme":"readme.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-12-19T14:19:33.000Z","updated_at":"2023-03-30T07:56:28.000Z","dependencies_parsed_at":"2022-08-21T10:10:40.106Z","dependency_job_id":null,"html_url":"https://github.com/infostreams/snippets","commit_stats":null,"previous_names":[],"tags_count":9,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infostreams%2Fsnippets","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infostreams%2Fsnippets/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infostreams%2Fsnippets/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/infostreams%2Fsnippets/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/infostreams","download_url":"https://codeload.github.com/infostreams/snippets/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251237873,"owners_count":21557357,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["kirbytext","philecms","php","snippets"],"created_at":"2024-11-11T10:54:42.633Z","updated_at":"2025-04-28T02:31:00.467Z","avatar_url":"https://github.com/infostreams.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Snippets\n\nA [PhileCMS](https://github.com/PhileCMS/Phile) plugin that extends the Markdown syntax to\neasily add links, images, videos or other content to your page. These 'snippets' are easy to\nadd and customize, and the plugin comes with a large selection of useful snippets out of the box.\n\nThis plugin works with the default Markdown parser, but it should also work with any of the other\nplugins that offer Markdown alternatives. It should even work if applied to regular HTML files.\n\n## Installation\n\n### With composer\n\n    php composer.phar require infostreams/snippets:*\n\n### Download \n\n* Install [Phile](https://github.com/PhileCMS/Phile)\n* Clone this repo into plugins/infostreams/snippets\n\n\n### Activation\n\nAfter you have installed the plugin. You need to add the following line to your config.php file:\n\n    $config['plugins']['infostreams\\\\snippets'] = array('active' =\u003e true);\n\n\n## What it does\n\nWith this plugin you can include pre-defined HTML snippets in your Markdown. This means you can\nwrite things like:\n\n    This is some text before I introduce you to the main point of this example, the YouTube video\n    that I want to include here:\n\n    (youtube: https://www.youtube.com/watch?v=mSB71jNq-yQ)\n\n    In case you can't see that video, you can have a look at the slideshow that I'll include for\n    your pleasure: (slideshow: [images/a.jpg, images/b.jpg, images/c.jpg] heading: Awesome slideshow)\n\n    I've taken these images from (link: site.com text: this site)\n\nBasically it extends standard Markdown syntax to make it easier to write interactive web pages\nwith more than just basic formatting. Markdown is great for adding headings, bold text, links and\nlists to your page, but it has almost no provisions for adding other elements to your page. With\nSnippets you can add these elements easily. You can use one of the many included snippets, or\nyou can easily define new ones yourself.\n\n\n## Supported syntax\n\n**General note**: snippet tags can be specified over multiple lines, and attribute values can\nbe scalar values (strings or integers) or lists (arrays) of values - in which case they will be\nparsed as such.\n\n### Links\nYou can link to external sites and to pages on your own site:\n\n    (link: cnn.com)\n    (link: products/mastergrill5000)\n\nSpecify the link text as follows:\n\n    (link: cnn.com text: the site I was talking about)\n\nAdd a title that displays when you move your mouse over the link:\n\n    (link: cnn.com title: click to visit!)\n\nThe link opens in a popup by adding the 'popup' attribute:\n\n    (link: cnn.com popup: true)\n\nYou can specify a custom CSS class for styling purposes:\n\n    (link: cnn.com class: my-css-class)\n\nIt is possible to combine these attributes, or to leave attributes out:\n\n    (link: cnn.com class: my-css-class popup:true text:CNN title:Click to go to the CNN homepage)\n\n### Email addresses\nYou can link to email addresses like this:\n\n    (email: someone@example.com)\n\nProvide a text for the link:\n\n    (email: someone@example.com text:My email address)\n\nAdd a title that displays when you move your mouse over the link:\n\n    (email: someone@example.com title:Click to email me)\n\nYou can specify a custom CSS class for styling purposes:\n\n    (email: someone@example.com class: my-css-class)\n\n### Images\nYou can include images from your own site, or from external sites:\n\n    (image: products/mastergrill5000/grilling.jpg)\n    (image: https://raw.githubusercontent.com/dcurtis/markdown-mark/master/png/66x40-solid.png)\n\nSet the width and height:\n\n    (image: products/mastergrill5000/grilling.jpg width:400)\n    (image: products/mastergrill5000/grilling.jpg width:400 height:600)\n\nSpecify alt text:\n\n    (image: products/mastergrill5000/grilling.jpg alt:Smoking!)\n\nAdd a caption:\n\n    (image: products/mastergrill5000/grilling.jpg caption:Grilling on the MasterGrill5000)\n\nSpecify a CSS class:\n\n    (image: products/mastergrill5000/grilling.jpg class:highlight)\n\nLink the image to a page or an external site:\n\n    (image: products/mastergrill5000/grilling.jpg link:products/mastergrill5000)\n    (image: products/mastergrill5000/amazon.jpg link:amazon.com/buy-the-mg5000)\n\nAdd a 'srcset' attribute to deal with responsive images:\n\n    (image: products/mastergrill5000/grilling.jpg srcset:products/mastergrill5000/grilling@2x.jpg 2x)\n\n### Files\n\nInclude files from your own site or from external sites:\n\n    (file: products/brochure.pdf)\n    (file: https://bitcoin.org/bitcoin.pdf)\n\nSpecify a text for the link:\n\n    (file: products/brochure.pdf text:our brochure)\n\nForce download of the file (limited browser support unfortunately):\n\n    (file: products/brochure.pdf download:true)\n\nSpecify a CSS class:\n\n    (file: products/brochure.pdf class:highlight)\n\n### YouTube videos\n\nEmbed a YouTube video in your document:\n\n    (youtube: https://www.youtube.com/watch?v=mSB71jNq-yQ)\n\nSpecify width and/or height:\n\n    (youtube: https://www.youtube.com/watch?v=mSB71jNq-yQ width:640)\n    (youtube: https://www.youtube.com/watch?v=mSB71jNq-yQ width:640 height:480)\n\n### Vimeo videos\n\nEmbed a Vimeo video in your document:\n\n    (vimeo: http://vimeo.com/63968108)\n\nSpecify width and/or height:\n\n    (vimeo: http://vimeo.com/63968108 width:700)\n    (vimeo: http://vimeo.com/63968108 width:700 height:393)\n\nOptions to include portrait, title and byline:\n\n    (vimeo: http://vimeo.com/63968108 portrait:false)\n    (vimeo: http://vimeo.com/63968108 portrait:false byline:false)\n    (vimeo: http://vimeo.com/63968108 portrait:false byline:false title:true)\n\n### Twitter\n\nEmbed a link to a Twitter profile:\n\n    (twitter: @nytimes)\n\nEmbed a link to a Twitter hashtag:\n\n    (twitter: #superimportant)\n\nEmbed a link to a Twitter search:\n\n    (twitter: #superimportant keywords)\n\nSpecify text for the link:\n\n    (twitter: @nytimes text:The New York Times on Twitter)\n\nSpecify a CSS class:\n\n    (twitter: @nytimes class:twitter-button)\n\n### Gist\n\nEmbed a Github Gist:\n\n    (gist: https://gist.github.com/1)\n\nDisplay a specific file in that gist:\n\n    (gist: https://gist.github.com/1 file: gistfile1.txt)\n\n### Telephone numbers\nAdd a link to a telephone number:\n\n    (tel: 555-0100)\n\nSpecify which text to use for the link:\n\n    (tel: 555-0100 text:Call me!)\n\nYou can specify a custom CSS class for styling purposes:\n\n    (tel: 555-0100 class:phone)\n\n\n# Adding your own snippets\n\nIt is very easy to define your own snippets. Most likely, you will want to do this through your\nPhileCMS configuration file:\n\n## Simple case\nExample:\n\n    $config['plugins']['infostreams\\\\snippets']['snippets'] = array(\n        'skype' =\u003e function($name, $action=\"call\", $text=null) {\n                       if (is_null($text)) {\n                         $text = \"Contact '$name' on Skype\";\n                       }\n                       return \"\u003ca href='skype:$name?$action'\u003e$text\u003c/a\u003e\";\n                   }\n    );\n\nThis adds a 'skype' snippet that you can use (in your markdown) as follows:\n\n    (skype: myfriend)\n\nThis would be rendered as:\n\n    \u003ca href='skype:myfriend?call'\u003eContact 'myfriend' on Skype\u003c/a\u003e\n\nThe PHP function has two more parameters, which means that the 'skype' snippets allows for\ntwo more attributes to be specified, as in:\n\n    (skype: my.account.on.skype action:chat text:Chat to me on Skype!)\n\nThis would produce the following HTML:\n\n    \u003ca href='skype:my.account.on.skype?chat'\u003eChat to me on Skype!\u003c/a\u003e\n\n## Using existing functions\n\nFirst, define your snippet in a class somewhere, and make sure it gets included:\n\n    class MySnippets {\n        public function skype($name, $action=\"call\", $text=null) {\n            if (is_null($text)) {\n                $text = \"Contact '$name' on Skype\";\n            }\n            return \"\u003ca href='skype:$name?$action'\u003e$text\u003c/a\u003e\";\n        }\n    }\n\nThen, add the 'skype' snippet to the Snippets config:\n\n    $config['plugins']['infostreams\\\\snippets']['snippets'] = array(\n        'skype' =\u003e array(new MySnippets(), 'skype'),\n    );\n\n## Using a Snippets class\n\nIt is also possible to define a class with multiple Snippets and add them all at once.\nFirst, define your class, and make sure it extends the ```\\Phile\\Plugin\\Infostreams\\Snippets\\Snippets```\nclass (which gives you access to some common functionality). Then, make sure that it is included by \nPhileCMS. There's a step-by-step guide [here](https://github.com/infostreams/snippets/issues/2#issuecomment-95512554) \nthat explains how to do that properly.\n\n    class MySnippets extends \\Phile\\Plugin\\Infostreams\\Snippets\\Snippets {\n        public function skype($name, $action=\"call\", $text=null) {\n            if (is_null($text)) {\n                $text = \"Contact '$name' on Skype\";\n            }\n            return \"\u003ca href='skype:$name?$action'\u003e$text\u003c/a\u003e\";\n        }\n\n        public function facebook($who, $attribute, $other_attribute) {\n            // ...\n        }\n\n        public function scroller($pictures) {\n            // ...\n        }\n\n        public function youtube_popup($link) {\n            // ...\n        }\n    }\n\nNow, you can add the `skype`, `facebook`, `scroller` and `youtube_popup` snippets (and any future\nones you define) by adding the following code to PhileCMS's configuration file:\n\n    $config['plugins']['infostreams\\\\snippets']['snippets'] = array(\n        new MySnippets(),\n        'some_other_snippet' =\u003e function($a, $b) { },\n        'yet_another_snippet' =\u003e array(new MyOtherClass(), 'method')\n    );\n\nFor convenience and aesthetic reasons, snippets that have an underscore in their name (such as\n`youtube_popup`) can also be used with a dash instead. So instead of writing `(youtube_popup: ....)`\nyou can also write `(youtube-popup: ....)`.\n\n# Attribute values: arrays and JSON\n\nParameter values don't need to be just strings or numbers. They can be arrays too! You can even\nprovide JSON strings - they will be parsed and converted into something that you can use inside\nyour snippet. For example, the following code defines a 'slideshow' snippet:\n\n    $config['plugins']['infostreams\\\\snippets']['snippets'] = array(\n        'slideshow' =\u003e function($images, $header=\"\") {\n                       $html = \"\";\n                       if (!is_null($text)) {\n                         $html .= \"\u003ch1\u003e\" . $header . \"\u003c/h1\u003e\";\n                       }\n                       if (is_array($images)) {\n                         $html .= \"\\n\u003cul\u003e\";\n                         foreach ($images as $key=\u003e$value) {\n                           if (is_numeric($key)) {\n                             $filename = $value;\n                             $description = \"\";\n                           } else {\n                             $filename = $key;\n                             $description = \"\u003cspan class='description'\u003e\" . $value . \"\u003c/span\u003e\";\n                           }\n                           $html .= \"\\n\u003cli\u003e\u003cimg src='$filename' /\u003e$description\u003c/li\u003e\";\n                         }\n                         $html .= \"\\n\u003cul\u003e\";\n                       }\n                       return \"\u003cdiv class='slideshow'\u003e\" . $html . \"\u003c/div\u003e\";\n                   }\n    );\n\nThis code generates the HTML for a simple slideshow. It can be used as follows:\n\n    (slideshow: [content/images/a.jpg, content/images/b.jpg, content/images/c.jpg] heading: It's a slideshow!)\n\nHere you see how you can provide multiple values for one field. The above example would create a\nslideshow for the images a.jpg, b.jpg and c.jpg.\n\nHowever, the snippet can also be used to label each image in the slideshow with a description. That\ncan be done as follows. For readability, the snippet is wrapped over more than one line:\n\n    (slideshow: [\n        content/images/a.jpg: This is my description,\n        content/images/b.jpg: \"This one description, it contains a comma -- so we wrap it in quotes\"\n        content/images/c.jpg: However\\, if you don't want to quote\\, you don't need to\n                              - it could get ugly quickly though\n        ]\n        heading: It's a slideshow!)\n\nThe list of images is now a PHP-like array of (key, value) pairs. The 'key' is the filename of the\nimage, the 'value' is the description of the image. This way, you can write snippets that only work\nif the author gives it more than one value - such as is the case in a slideshow. It is possible to\nbuild elaborate data structures using this syntax.\n\n## Escaping text\nYou can observe that in most cases you don't need to surround the description by quotation marks. You\ncan if you want to, though -- as is shown in the second description (the one for b.jpg).\n\nAs long as the text doesn't contain a comma, colon, or one of '[', '{', '}' or ']', then you don't\nneed quotation marks. If it *does* contain one of those, you can 'escape' it by placing a '\\\\' before\nthe offending character, as is shown in the third description (the one for c.jpg).\n\n## JSON\nFinally, if you don't like the above syntax, you can also just use plain old JSON:\n\n    (slideshow:  {\n         \"content\\/images\\/a.jpg\":\"This is my description\",\n         \"content\\/images\\/b.jpg\":\"This one description, it contains a comma -- so we wrap it in quotes\",\n         \"content\\/images\\/c.jpg\":\"However, if you don't want to quote, you don't need to - it could get ugly quickly though\"\n        }\n        heading: It's a slideshow!)\n\n\n### Kirbytext\nThis plugin is an open source (MIT licensed) re-implementation and extension of [Kirbytext](http://getkirby.com/docs/content/text).\n\nIt correctly parses *most* of Kirbytext's syntax, even though the resulting HTML might differ.\nThere is no guarantee of compatibility between the two, although a high level of backwards\ninteroperability is one of the design goals.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfostreams%2Fsnippets","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finfostreams%2Fsnippets","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finfostreams%2Fsnippets/lists"}