From 29c49f6a19f4bbf79a890595de5142ebdc0d19e0 Mon Sep 17 00:00:00 2001 From: Charlie Powell Date: Fri, 27 Oct 2023 01:09:39 -0400 Subject: [PATCH] Documentation --- CHANGELOG.md | 4 +- README.md | 24 ++-- RELEASE.md | 157 ++--------------------- docs/INSTALL.apache.md | 16 ++- docs/authoring-pages.md | 52 +++----- docs/cms-author.md | 4 +- docs/cms-button.md | 2 +- docs/cms-icon.md | 2 +- docs/cms-mastodon-share.md | 6 +- docs/cms-pagelist.md | 11 +- docs/cms-search.md | 2 +- docs/markdown-extended-attributes.md | 54 ++++++++ docs/upgrade-notes/upgrade-2.x-to-3.0.md | 94 ++++++++++++++ docs/upgrade-notes/upgrade-3.0-to-3.1.md | 15 +++ docs/upgrade-notes/upgrade-3.1-to-4.0.md | 26 ++++ docs/upgrade-notes/upgrade-4.0-to-4.1.md | 9 ++ src/client/addons/cms-author.js | 2 +- 17 files changed, 278 insertions(+), 202 deletions(-) create mode 100644 docs/markdown-extended-attributes.md create mode 100644 docs/upgrade-notes/upgrade-2.x-to-3.0.md create mode 100644 docs/upgrade-notes/upgrade-3.0-to-3.1.md create mode 100644 docs/upgrade-notes/upgrade-3.1-to-4.0.md create mode 100644 docs/upgrade-notes/upgrade-4.0-to-4.1.md diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a523cb..0da38e4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,4 +1,4 @@ -## 4.NEXT - 2023-XX-XX +## 4.1.0 - 2023-XX-XX ### New Features @@ -11,10 +11,12 @@ * Fix cms-* plugins trying to run before CMS was initialized * Switch example site to use minified version of app by default * Include default config for Apache expiry headers (for caching) +* Fix paragraph stealing extended attributes for simple blocks ### Changes * Mastodon Share is now an element as opposed to a plugin +* Switch to `is=...` for all custom elements ## 4.0.2 - 2023-10-23 diff --git a/README.md b/README.md index 932d9ca..a9185fb 100644 --- a/README.md +++ b/README.md @@ -15,9 +15,12 @@ the auto-index feature in either or [Nginx](https://nginx.org/en/docs/http/ngx_http_autoindex_module.html) and performs all processing of templates and content within the browser. -Note* there _is_ a server-side component written as a Python CGI script to -better facilitate crawlers, bots, and search engines. This component utilizes the -same flat files and templates as the client-side application. +Note* for SEO reasons, there is a server-side Python component +which will return a generated version of the requested page similar to the +client-side application. This is unnecessary for normal users, but is required +to ensure that crawlers can access the site data. + +This feature can be disabled via `.htaccess` or `nginx.conf` if desired. Because there is no database, registry, or administration of pages, deploying new pages is as simple as just uploading Markdown files to your server. @@ -45,8 +48,10 @@ This project is originally based from * Search, filtering, tagging and sorting * Apache, Nginx, Mail-in-a-box, and Nextcloud support * Small footprint -* [marked.js](https://github.com/markedjs/marked) embedded -* Automatic body classes based on page +* [marked.js](https://github.com/markedjs/marked) embedded (still included, but not + used by default) +* [Remarkable](https://github.com/jonschlinkert/remarkable) embedded +* Automatic body classes based on page (addon) * Native JS events * Full [History API](https://developer.mozilla.org/en-US/docs/Web/API/History) support * Crawler and SEO support for most content @@ -62,7 +67,9 @@ Check out a [live working site](https://veraciousnetwork.com)! 1. Download the [latest release](https://github.com/cdp1337/markdownmaster/releases/latest) 2. Setup environment, refer to specific documentation for - [NextCloud](docs/INSTALL.nextcloud-nginx.md) or [Mail-in-a-Box](docs/INSTALL.mailinabox.md) + [NextCloud](docs/INSTALL.nextcloud-nginx.md), + [Mail-in-a-Box](docs/INSTALL.mailinabox.md), + or [Apache](docs/INSTALL.apache.md) for more information. 3. [Configure config.js and config.ini](docs/site-configuration.md) to your liking @@ -76,8 +83,9 @@ take a look through the other [post examples](examples/posts/) and the various * [Using plugins](docs/plugins-overview.md) * [Hooking into native events](docs/document-events.md) * [Authoring content](docs/authoring-pages.md) -* [Content Sorting](docs/sorting.md) -* [Development Guide](docs/development.md) +* [Extended attributes](docs/markdown-extended-attributes.md) +* [Content sorting](docs/sorting.md) +* [Development guide & build instructions](docs/development.md) ## How it works diff --git a/RELEASE.md b/RELEASE.md index 7ada3fc..f889569 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -3,155 +3,26 @@ ## New Features -* Include a simple background-slider plugin -* Include fslightbox-basic for a simple lightbox +* Add 'random' as supported sort parameter +* Paginate now supports 'page' parameter +* Page-list now supports 'limit' parameter ## Fixes -* Fix support for Apache web servers - +* Fix cms-* plugins trying to run before CMS was initialized +* Switch example site to use minified version of app by default +* Include default config for Apache expiry headers (for caching) +* Fix paragraph stealing extended attributes for simple blocks ## Changes +* Mastodon Share is now an element as opposed to a plugin +* Switch to `is=...` for all custom elements +## Upgrade Notes -## Upgrade from 2.x - -Since this has been a substantial rewrite, some features will require updating, -(depending on what is used on your specific site). - -### URLs - -Page URLs have been changed from query hashes to full standard URLs via the History API. -This requires a new `.htaccess` or `nginx.conf` to be installed -(depending on the server you chose). Consult the respective file within `examples/`. - -### Plugins - -Plugins have been retooled and need refactored to work correctly. -Given the default example plugin: - -```js -// 2.x Example plugin -function myPlugin() { - // Do some code - console.log('loading test plugin'); -} - -// Config -var config = { - - // ... - - // Pass in any custom functions or plugins here and access the CMS object. - plugins: [ - myPlugin, - ], - - // ... - - // This function will be called once the CMS instance is loaded and ready. - onload: function() { - - // ... - - // Access the loaded plugins like this. - blog.myPlugin(); - }, -}; -``` - -This example plugin would need to be rewritten to: - -```js -// 3.x+ plugin -blog.registerPlugin( - 'myPlugin', - { - init: () => { - // Do some code - console.log('loading test plugin'); - } - } -); - -// Access the loaded plugins like this. -blog.getPlugin('myPlugin'); -``` - -### onload/onroute - -The configurable options `onload` and `onroute` are still supported, -but this functionality has been ported to the following code: - -```js -/** - * Called immediately upon successful initialization of the CMS - * - * @param {CMS} event.detail.cms The CMS object passed for reference - */ -document.addEventListener('cms:load', event => { - event.detail.cms.debuglog('CMS initialized and ready to run user-specific code!', event.detail.cms); -}); - -/** - * Called after any page load operation - * - * @param {CMS} event.detail.cms CMS object for reference if needed - * @param {FileCollection[]|null} event.detail.collection Collection of files to view for listing pages - * @param {File|null} event.detail.file Single file to view when available - * @param {string} event.detail.mode Type of view, usually either "list", "single", or error. - * @param {string} event.detail.search Any search query - * @param {string} event.detail.tag Any tag selected to view - * @param {string} event.detail.type Content type selected - */ -document.addEventListener('cms:route', event => { - event.detail.cms.debuglog('Page being displayed', event.detail); -}); -``` - - -## Upgrade from 3.0.x - -1. Configure `cgi-bin/config.ini` with values that mimic `js/config.js` -2. Upload `cgi-bin` to your server -3. Add new directives from `nginx.conf` into your site config -4. Run the following code (with the appropriate SITEPATH) - -```bash -apt install fcgiwrap python3 python3-venv -python3 -m venv /opt/markdownmaster -/opt/markdownmaster/bin/pip3 install Markdown beautifulsoup4 python-frontmatter lxml -chmod +x "${SITEPATH}/cgi-bin/crawler.py" -chmod +x "${SITEPATH}/cgi-bin/sitemap.py" -chmod +x "${SITEPATH}/cgi-bin/meta.py" -``` - - -## Upgrade from 3.1.x - ---- - -Tags and other lists in Markdown files now expect to be YAML-compatible lists - -* `tags: blah, foo` => `tags: [blah, foo]` -* Dates listed as `date: 2023-01-01` will be rendered as Date objects, -switch to `date: '2023-01-01'` (with quotes) for best results - ---- - -Banners and images no longer auto-resolve as URLs, instead `src` or `href` needs to be -used in YAML data - -* `banner: somefile.jpg` => `banner: { src: somefile.jpg }` - ---- - -Moved some plugins to built-in - -* `site.enablePlugin(['pagelist'])` => N/A (built-in) -* `site.enablePlugin(['search'])` => N/A (built-in) -* `site.enablePlugin(['remarkable'])` NEW RENDERER - ---- \ No newline at end of file +* [From 2.x](docs/upgrade-notes/upgrade-2.x-to-3.0.md) +* [From 3.0](docs/upgrade-notes/upgrade-3.0-to-3.1.md) +* [From 3.1](docs/upgrade-notes/upgrade-3.1-to-4.0.md) +* [From 4.0](docs/upgrade-notes/upgrade-4.0-to-4.1.md) \ No newline at end of file diff --git a/docs/INSTALL.apache.md b/docs/INSTALL.apache.md index 5777948..2b774e0 100644 --- a/docs/INSTALL.apache.md +++ b/docs/INSTALL.apache.md @@ -1,6 +1,8 @@ Apache2 can be used to host your own site, but needs a module to be enabled for best results. -`rewrite` is required as it will allow URLs to be rewritten and resolved via the History API. This will also perform rewrites for search crawlers to ensure they retrieve content when crawling the various .html links. +`rewrite` is required as it will allow URLs to be rewritten and resolved via the History API. +This will also perform rewrites for search crawlers to ensure they retrieve content +when crawling the various .html links. ## Setup apache (tested on Debian/Ubuntu) @@ -11,17 +13,21 @@ Enable the modules necessary and restart the web server. ## Install Files -Extract the application, (including hidden `.htaccess` files) to `/var/www/html` (or other directory should you choose). +Extract the application, (including hidden `.htaccess` files) to `/var/www/html`, +`public_html`, or whatever directory your website resides. ## Configure Environment -If your web application is installed in a directory OTHER than the default top-level path, edit `.htaccess` and set the `RewriteBase` directive as necessary. For example if your site is installed in `/var/www/html/mycms` and is retrieved via `https://domain.tld/mycms`, your `.htaccess` should resemble the following: +If your web application is installed in a directory OTHER than the default top-level path, +edit `.htaccess` and set the `RewriteBase` directive as necessary. +For example if your site is installed in `/var/www/html/mycms` +and is retrieved via `https://domain.tld/mycms`, your `.htaccess` should resemble the following: ```.htaccess # Set this line to the value of config.webpath - RewriteBase /mycms/ + RewriteBase /mycms/ ``` ## Configure Application -Follow standard steps for configuring the application via `js/config.js`. \ No newline at end of file +Follow standard steps for configuring the application via `js/config.js` and `cgi-bin/config.ini`. \ No newline at end of file diff --git a/docs/authoring-pages.md b/docs/authoring-pages.md index 631c6e6..4544c44 100644 --- a/docs/authoring-pages.md +++ b/docs/authoring-pages.md @@ -105,6 +105,23 @@ call_to_action: | tags | Comma-separated list of tags for the content on this page | | image | Fully resolve or relative path to preview image of this page | +### Protected Attributes + +DO NOT USE THESE! +These are reserved for internal use only, but are available for use in your templates. + +| Attribute | Description | +|-------------|-----------------------------------------------------------------------| +| body | The raw markdown content of this page | +| bodyLoaded | The rendered HTML content of this page | +| config | The configuration object for this page | +| content | The rendered HTML content of this page | +| name | The filename of this page | +| permalink | The permalink of this page | +| type | The type of content this is (page, post, etc) | +| url | The URL of this page | + + Other attributes can be used, but will need to be added within your layout templates to make use of them. @@ -149,38 +166,3 @@ relative to that file. Top-level paths (starting with `/`) and absolute request (`https://...`) paths are also supported. -## Extended Markdown Functionality - -All base markdown features will work, and a number of extended features have -been added to better support web publishing. - -### HTML Attributes - -HTML attributes can be set on some elements, including: - -* paragraphs -* links -* images - -To use HTML attributes, append `{...}` to the end of the line with the HTML tags inside. -As some examples: - -Short paragraph with `class="center"` added - -```markdown -This is a short example paragraph {.center} -``` - -This link will have a `title` and `target` set - -```md -[Go Search](https://www.duckduckgo.com) {title="Search for something" target=_blank} -``` - -This image will have a border - -```markdown -![test image](test.png) {style="border:5px solid pink;"} -``` - -Any valid HTML tag can be used and CSS shorthand for class (`.` prefix) and ID (`#` prefix) are also supported. diff --git a/docs/cms-author.md b/docs/cms-author.md index 9db8cbc..e991856 100644 --- a/docs/cms-author.md +++ b/docs/cms-author.md @@ -24,6 +24,8 @@ The template to use for rendering the author content ```html <% if(data.author) { %> - <%= data.author %> +
+ <%= data.author %> +
<% } %> ``` \ No newline at end of file diff --git a/docs/cms-button.md b/docs/cms-button.md index 65d8840..8047832 100644 --- a/docs/cms-button.md +++ b/docs/cms-button.md @@ -35,5 +35,5 @@ Renders to Also usable from within Markdown pages ```markdown -[Download this Thing](https://site.tld) {is=cms-button icon=download} +[Download this Thing](https://site.tld){is=cms-button icon=download} ``` \ No newline at end of file diff --git a/docs/cms-icon.md b/docs/cms-icon.md index 6433165..9029cba 100644 --- a/docs/cms-icon.md +++ b/docs/cms-icon.md @@ -15,5 +15,5 @@ If a "brand" icon is used, the brand library will be loaded. **Example** ```.html - + ``` diff --git a/docs/cms-mastodon-share.md b/docs/cms-mastodon-share.md index 6e595fb..291d4f0 100644 --- a/docs/cms-mastodon-share.md +++ b/docs/cms-mastodon-share.md @@ -11,8 +11,8 @@ At the moment no parameters are configurable **Example** ```.html - - + + Share on Mastodon - + ``` diff --git a/docs/cms-pagelist.md b/docs/cms-pagelist.md index 8eb36ff..b775055 100644 --- a/docs/cms-pagelist.md +++ b/docs/cms-pagelist.md @@ -18,7 +18,14 @@ Render a list of pages which match given parameters. **Example** ```.html - +
Loading Content... - +
``` diff --git a/docs/cms-search.md b/docs/cms-search.md index e97b7ac..c22f818 100644 --- a/docs/cms-search.md +++ b/docs/cms-search.md @@ -11,5 +11,5 @@ At the moment no parameters are configurable **Example** ```.html - + ``` diff --git a/docs/markdown-extended-attributes.md b/docs/markdown-extended-attributes.md new file mode 100644 index 0000000..68d52e6 --- /dev/null +++ b/docs/markdown-extended-attributes.md @@ -0,0 +1,54 @@ +--- +author: Charlie Powell +tags: [Howto, Markdown, Authoring] +--- + +# Extended Markdown Functionality + +All base markdown features will work, and a number of extended features have +been added to better support web publishing. + +## HTML Attributes + +HTML attributes can be set on some elements, including: + +* paragraphs +* links +* images + +To use HTML attributes, append `{...}` to the end of the line with the HTML tags inside. +As some examples: + +Short paragraph with `class="center"` added + +```markdown +This is a short example paragraph {.center} +``` + +This link will have a `title` and `target` set. +Since both paragraphs and links support extended attributes, try to ensure +no space between the link and curly brace. + +```md +[Go Search](https://www.duckduckgo.com){title="Search for something" target=_blank} +``` + +This image will have a border + +```markdown +![test image](test.png){style="border:5px solid pink;"} +``` + +### Valid Attributes and Shorthand + +Below is a list of attributes and shorthand versions, +but ANY HTML ATTRIBUTE is supported. + +| Attribute | Description | Example | +|------------|-------------------------|------------------------------------| +| "." prefix | Shorthand for class=... | `{.center}` | +| "#" prefix | Shorthand for id=... | `{#myid}` | +| style | CSS style attributes | `{style="border:5px solid pink;"}` | +| title | Title attribute | `{title="My Title"}` | +| target | Target attribute | `{target=_blank}` | +| data-* | Data attributes | `{data-foo="bar"}` | diff --git a/docs/upgrade-notes/upgrade-2.x-to-3.0.md b/docs/upgrade-notes/upgrade-2.x-to-3.0.md new file mode 100644 index 0000000..27475cb --- /dev/null +++ b/docs/upgrade-notes/upgrade-2.x-to-3.0.md @@ -0,0 +1,94 @@ +# Upgrade from 2.x to 3.0 + +Since this has been a substantial rewrite, some features will require updating, +(depending on what is used on your specific site). + +## URLs + +Page URLs have been changed from query hashes to full standard URLs via the History API. +This requires a new `.htaccess` or `nginx.conf` to be installed +(depending on the server you chose). Consult the respective file within `examples/`. + +## Plugins + +Plugins have been retooled and need refactored to work correctly. +Given the default example plugin: + +```js +// 2.x Example plugin +function myPlugin() { + // Do some code + console.log('loading test plugin'); +} + +// Config +var config = { + + // ... + + // Pass in any custom functions or plugins here and access the CMS object. + plugins: [ + myPlugin, + ], + + // ... + + // This function will be called once the CMS instance is loaded and ready. + onload: function() { + + // ... + + // Access the loaded plugins like this. + blog.myPlugin(); + }, +}; +``` + +This example plugin would need to be rewritten to: + +```js +// 3.x+ plugin +blog.registerPlugin( + 'myPlugin', + { + init: () => { + // Do some code + console.log('loading test plugin'); + } + } +); + +// Access the loaded plugins like this. +blog.getPlugin('myPlugin'); +``` + +## onload/onroute + +The configurable options `onload` and `onroute` are still supported, +but this functionality has been ported to the following code: + +```js +/** + * Called immediately upon successful initialization of the CMS + * + * @param {CMS} event.detail.cms The CMS object passed for reference + */ +document.addEventListener('cms:load', event => { + event.detail.cms.debuglog('CMS initialized and ready to run user-specific code!', event.detail.cms); +}); + +/** + * Called after any page load operation + * + * @param {CMS} event.detail.cms CMS object for reference if needed + * @param {FileCollection[]|null} event.detail.collection Collection of files to view for listing pages + * @param {File|null} event.detail.file Single file to view when available + * @param {string} event.detail.mode Type of view, usually either "list", "single", or error. + * @param {string} event.detail.search Any search query + * @param {string} event.detail.tag Any tag selected to view + * @param {string} event.detail.type Content type selected + */ +document.addEventListener('cms:route', event => { + event.detail.cms.debuglog('Page being displayed', event.detail); +}); +``` diff --git a/docs/upgrade-notes/upgrade-3.0-to-3.1.md b/docs/upgrade-notes/upgrade-3.0-to-3.1.md new file mode 100644 index 0000000..52ebd28 --- /dev/null +++ b/docs/upgrade-notes/upgrade-3.0-to-3.1.md @@ -0,0 +1,15 @@ +# Upgrade from 3.0 to 3.1 + +1. Configure `cgi-bin/config.ini` with values that mimic `js/config.js` +2. Upload `cgi-bin` to your server +3. Add new directives from `nginx.conf` into your site config +4. Run the following code (with the appropriate SITEPATH) + +```bash +apt install fcgiwrap python3 python3-venv +python3 -m venv /opt/markdownmaster +/opt/markdownmaster/bin/pip3 install Markdown beautifulsoup4 python-frontmatter lxml +chmod +x "${SITEPATH}/cgi-bin/crawler.py" +chmod +x "${SITEPATH}/cgi-bin/sitemap.py" +chmod +x "${SITEPATH}/cgi-bin/meta.py" +``` diff --git a/docs/upgrade-notes/upgrade-3.1-to-4.0.md b/docs/upgrade-notes/upgrade-3.1-to-4.0.md new file mode 100644 index 0000000..7f1d2a8 --- /dev/null +++ b/docs/upgrade-notes/upgrade-3.1-to-4.0.md @@ -0,0 +1,26 @@ +# Upgrade from 3.1 to 4.0 + +--- + +Tags and other lists in Markdown files now expect to be YAML-compatible lists + +* `tags: blah, foo` => `tags: [blah, foo]` +* Dates listed as `date: 2023-01-01` will be rendered as Date objects, + switch to `date: '2023-01-01'` (with quotes) for best results + +--- + +Banners and images no longer auto-resolve as URLs, instead `src` or `href` needs to be +used in YAML data + +* `banner: somefile.jpg` => `banner: { src: somefile.jpg }` + +--- + +Moved some plugins to built-in + +* `site.enablePlugin(['pagelist'])` => N/A (built-in) +* `site.enablePlugin(['search'])` => N/A (built-in) +* `site.enablePlugin(['remarkable'])` NEW RENDERER + +--- \ No newline at end of file diff --git a/docs/upgrade-notes/upgrade-4.0-to-4.1.md b/docs/upgrade-notes/upgrade-4.0-to-4.1.md new file mode 100644 index 0000000..8711f55 --- /dev/null +++ b/docs/upgrade-notes/upgrade-4.0-to-4.1.md @@ -0,0 +1,9 @@ +# Upgrade from 4.0 to 4.1 + + +## CustomElements + +CustomElements have changed their tags + +* from `` to `
` +* from `` to `
` diff --git a/src/client/addons/cms-author.js b/src/client/addons/cms-author.js index 0112207..39ede26 100644 --- a/src/client/addons/cms-author.js +++ b/src/client/addons/cms-author.js @@ -21,7 +21,7 @@ */ /** - * element definition + *
element definition */ export default class CMSAuthorElement extends HTMLElement { static get observedAttributes() {