{"id":21319551,"url":"https://github.com/simplajs/simpla-article","last_synced_at":"2025-12-12T05:55:49.395Z","repository":{"id":58239165,"uuid":"92194945","full_name":"simplajs/simpla-article","owner":"simplajs","description":"Write longform, rich-media articles seamlessly inline","archived":false,"fork":false,"pushed_at":"2017-12-15T05:55:17.000Z","size":173,"stargazers_count":8,"open_issues_count":6,"forks_count":0,"subscribers_count":6,"default_branch":"master","last_synced_at":"2024-11-11T23:51:45.141Z","etag":null,"topics":["article","content-management","custom-element","richtext","simpla","web-components"],"latest_commit_sha":null,"homepage":"https://www.simplajs.org","language":"HTML","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/simplajs.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":"2017-05-23T16:23:11.000Z","updated_at":"2018-10-04T22:57:34.000Z","dependencies_parsed_at":"2022-08-31T03:01:55.607Z","dependency_job_id":null,"html_url":"https://github.com/simplajs/simpla-article","commit_stats":null,"previous_names":["simplaelements/simpla-article"],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplajs%2Fsimpla-article","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplajs%2Fsimpla-article/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplajs%2Fsimpla-article/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplajs%2Fsimpla-article/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simplajs","download_url":"https://codeload.github.com/simplajs/simpla-article/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225795416,"owners_count":17525316,"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":["article","content-management","custom-element","richtext","simpla","web-components"],"created_at":"2024-11-21T19:42:46.927Z","updated_at":"2025-12-12T05:55:49.318Z","avatar_url":"https://github.com/simplajs.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simpla Article\n[![Build status][travis-badge]][travis-url] ![Size][size-badge] ![Version][bower-badge] [![Published][webcomponents-badge]][webcomponents-url]\n\nSimpla-article lets you write longform, rich-media articles seamlessly inline with a single HTML element. It's built on the [Simpla][simpla] content system.\n\n\u003c!---\n```\n\u003ccustom-element-demo\u003e\n  \u003ctemplate\u003e\n    \u003cscript src=\"https://unpkg.com/webcomponents.js@^0.7.24/webcomponents-lite.min.js\"\u003e\u003c/script\u003e\n    \u003cscript src=\"https://unpkg.com/simpla@^2.0.0\"\u003e\u003c/script\u003e\n    \u003cscript\u003e\n      Simpla.init('local');\n      Simpla.editable(true);\n    \u003c/script\u003e\n\n    \u003clink rel=\"import\" href=\"simpla-article.html\"\u003e\n\n    \u003cstyle\u003e\n      body {\n        font-family: sans-serif;\n        color: #303c46;\n        padding: 1em 1.5em;\n      }\n\n      simpla-article p {\n        line-height: 1.6;\n      }\n\n      simpla-article h1, h2 {\n        font-weight: 400;\n        line-height: 1.3;\n      }\n\n      simpla-article h1 {\n        font-size: 1.8em;\n        font-weight: 300;\n      }\n\n      simpla-article img {\n        max-width: 100%;\n      }\n\n      simpla-article img[data-alignment=\"right\"] {\n        margin-right: -1em;\n      }\n\n      simpla-article img[data-alignment=\"left\"] {\n        margin-left: -1em;\n      }\n\n      simpla-article blockquote {\n        border-left: 1px solid lightGrey;\n        padding-left: 1em;\n        margin-left: 2em;\n        font-weight: 300;\n        overflow: hidden;\n        font-style: italic;\n      }\n\n      simpla-article blockquote p:first-of-type {\n        margin-top: 0.5em;\n      }\n\n      simpla-article blockquote p:last-of-type {\n        margin-bottom: 0.5em;\n      }\n\n      simpla-article a {\n        text-decoration: none;\n        color: #1bd4dc;\n      }\n    \u003c/style\u003e\n    \u003cnext-code-block\u003e\u003c/next-code-block\u003e\n  \u003c/template\u003e\n\u003c/custom-element-demo\u003e\n```\n--\u003e\n\n```html\n\u003csimpla-article path=\"/article\"\u003e\u003c/simpla-article\u003e\n```\n\n### Contents\n\n- [Installation and setup](#installation-and-setup)\n- [Writing articles](#writing-articles)\n  - [Editing inline](#editing-inline)\n- [Saving articles](#saving-articles)\n- [Styling article content](#styling-article-content)\n- [Initializing with static content](#initializing-with-static-content)\n- [Custom placeholders](#custom-placeholders)\n- [Typographer](#typographer)\n- [Readonly](#readonly)\n- [Contributing](#contributing)\n\n### Resources\n\n- [API reference][api]\n- [Demo][demo]\n- [License][license]\n\n## Installation and setup\n\nInstall simpla-article with Bower (Yarn support coming soon)\n\n```sh\n$ bower i simpla-article --save\n```\n\n[Setup Simpla][simpla-setup] on your page, then import simpla-article into your `\u003chead\u003e`\n\n```html\n\u003clink rel=\"import\" href=\"/bower_components/simpla-article/simpla-article.html\"\u003e\n```\n\nUse the `\u003csimpla-article\u003e` element wherever you want to create a new article. Give each article a unique `path`, where it will store its content in your project\n\n```html\n\u003csimpla-article path=\"/article\"\u003e\u003c/simpla-article\u003e\n```\n\n## Writing articles\n\nWrite and edit articles by entering edit mode with Simpla (which makes all Simpla elements on a page editable) or setting the `editable` property directly on an article element.\n\n```js\n// Enter edit mode\nSimpla.editable(true);\n```\n\n```html\n\u003c!-- Make only this article editable --\u003e\n\u003csimpla-article path=\"/article\" editable\u003e\u003c/simpla-article\u003e\n```\n\nEntering edit mode with Simpla is the recommended way to edit articles. It ensures all elements on a page remain in sync and updates Simpla's public `editable` state, which other elements may rely on.\n\n### Editing inline\n\nSimpla-article supports the following content types:\n\n- Formatted text (Bold/Italic)\n- Links\n- Headings\n- Blockquotes\n- Lists (ordered and unordered)\n- Embedded images\n\nTo format text and apply links, headings, and blockquotes, highlight the text you want to modify and use the appropriate tool from the toolbar.\n\nTo embed an image, focus on an empty line and tap the camera icon that appears to the left of the cursor. Once the image has been embedded select it to change its alignment.\n\nWrite lists inline, and they will be automatically converted to HTML lists by simpla-article.\n\n```\nUnordered list:\n- Item\n- Item 2\n\nOrdered list:\n1. Item\n2. Item 2\n```\n\n## Saving articles\n\nSave a simpla-article by calling Simpla's `save()` method, which saves all modified content on the page. It returns a promise.\n\n```js\n// Save all modified content on page\nSimpla.save();\n```\n\n\u003e You must be authenticated with Simpla before saving content\n\n## Styling article content\n\nSimpla-article doesn't style your content, and generates the same clean, semantic markup you would write if you were to code the content yourself.\n\n```css\nsimpla-article h1 {\n  font-size: 1.8em;\n  font-weight: 400;\n}\n```\n\nThese are the only HTML elements allowed by simpla-article's content model:\n\n- Paragraphs are wrapped in `\u003cp\u003e`\n- Bold text is wrapped in `\u003cstrong\u003e`\n- Italic text is wrapped in `\u003cem\u003e`\n- Links are wrapped in `\u003ca\u003e`\n- Blockquotes are wrapped in `\u003cblockquote\u003e`\n- Headings are wrapped in `\u003ch1\u003e` or `\u003ch2\u003e`\n- Lists use standard list elements (`\u003cul\u003e`, `\u003col\u003e`, `\u003cli\u003e`)\n- Embedded images use standard `\u003cimg\u003e`\n\nEmbedded images have a `data-alignment` attribute with the image's current alignment (eg: `data-alignment=\"left\"`). You can use this attribute to customize how aligned images behave.\n\n## Initializing with static content\n\nYou can write HTML content inside simpla-article just like you would with any other element. The HTML you insert will be parsed and sanitized into simpla-article's content model when you enter edit mode. If content for an article's `path` exists on Simpla's API any static content will be overwritten.\n\n```html\n\u003csimpla-article path=\"/article\"\u003e\n  \u003ch1\u003eSimpla Article\u003c/h1\u003e\n  \u003cp\u003eWrite longform, rich-media articles seamlessly inline\u003c/p\u003e\n\u003c/simpla-article\u003e\n```\n\nInitializing with static content is useful for converting existing sites to Simpla, or bootstrapping a project with predefined content. By putting markup inside `\u003csimpla-article\u003e` and then calling `Simpla.save()` you can easily set static content directly to Simpla's API.\n\n\u003e Since static content is overwritten by remote data, you should not have content inside `\u003csimpla-article\u003e` in production. If newer content gets saved you will experience FOUC (Flash Of Unformatted Content) when the static content is overwritten\n\n## Custom placeholders\n\nYou can set custom placeholders (displayed when simpla-article is editable and doesn't have content) with a `placeholder` attribute\n\n```html\n\u003csimpla-article \n  path=\"/article\" \n  placeholder=\"Tell your story\"\u003e\n\u003c/simpla-article\u003e\n```\n\n## Typographer\n\nSimpla-article applies 'smart typography' rules to its content, including:\n\n- Smart quotes (`\"` to `“`)\n- Automatic em dashes (`--` to `—`)\n- Automatic ellipses (`...` to `…`)\n\nYou can disable the smart typographer by giving simpla-article a `noTypographer` property\n\n```html\n\u003csimpla-article \n  path=\"/article\" \n  no-typographer\u003e\n\u003c/simpla-article\u003e\n```\n\n## Readonly\n\nSimpla-article has a `readonly` property that stops it from becoming editable, even if Simpla is in edit mode or you try to set `editable` on the element directly. This is useful for using simpla-article to purely consume and display content from Simpla's API.\n\n```html\n\u003csimpla-article path=\"/article\" readonly\u003e\u003c/simpla-article\u003e\n```\n\n## Contributing\n\nIf you find any issues with simpla-article please report them! If you'd like to see a new feature in supported file an issue or let us know in Simpla's public [Slack group][slack-url]. We also happily accept PRs. \n\n***\n\nMIT © [Simpla][simpla]\n\n[simpla]: https://www.simpla.io\n[simpla-setup]: https://docs.simpla.io/guides/get-started.html\n\n[api]: https://www.webcomponents.org/element/simplaio/simpla-article/page/API.md\n[demo]: https://www.webcomponents.org/element/simplaio/simpla-article/demo/demo/index.html\n[license]: https://github.com/simplaio/simpla-article/blob/master/LICENSE\n\n[bower-badge]: https://img.shields.io/bower/v/simpla-article.svg\n[travis-badge]: https://img.shields.io/travis/simplaio/simpla-article.svg\n[travis-url]: https://travis-ci.org/simplaio/simpla-article\n[size-badge]: http://img.badgesize.io/simplaio/simpla-article/master/simpla-article.html?compression=gzip\u0026label=render_bundle_%28gzip%29\n[webcomponents-badge]: https://img.shields.io/badge/webcomponents.org-published-blue.svg\n[webcomponents-url]: https://www.webcomponents.org/element/simplaio/simpla-article\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplajs%2Fsimpla-article","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimplajs%2Fsimpla-article","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplajs%2Fsimpla-article/lists"}