hasgeek / funnel

Website for hasgeek.com
https://hasgeek.com/
GNU Affero General Public License v3.0
46 stars 52 forks source link

Support for content layouts in Markdown #1981

Open jace opened 8 months ago

jace commented 8 months ago

Markdown offers this syntax for images, but with no control over size or positioning:

![Alt text for screen readers](/path/to/image.ext "Title attr on the <img> tag")

Markdown extensions like the attrs plugin offer a flexible syntax for attaching HTML attributes, allowing for layout control with CSS:

![alt](https://image.com){#id .class attr=value}

But this is unsafe for UGC websites because user-content can use system CSS classes and ids that mimic the system itself or interfere with system functionality. In addition, stylesheets are part of code and are version controlled independently from content, so this content is not archival-safe. Markup in Markdown should be semantic markup, and semantic styles should be well defined and supported long term. This PR attempts to define and support some common content patterns by enabling existing plugins in restricted contexts. Discussion in comments.

jace commented 8 months ago

CSS as UGC may be desirable as it allows users to define custom layouts independently. Since Funnel is designed to segment permissions at the account and project level, custom stylesheets can be located at either level (TBD as a separate ticket). Within the Markdown parser, this can be supported by enabling the attrs plugin with a custom validator:

jace commented 8 months ago

Image or image gallery embeds could use the container plugin for image(s) + caption. Typical layouts:

  1. Splash image (full width without margins, typically as a header, but sometimes mid-page too)
  2. Featured image (large, but with margins)
  3. Medium (centered on page, not excessively large)
  4. Sidebar (offset to a side, typically the first element in a paragraph of text)
::: splash-image
![Alt text](/path/to/image)
![Second image creates a carousel](/path/to/image)

Caption _with_ Markdown markup
:::
::: gallery
![Alt text](/path/to/image)
![Both images appear as clickable thumbnails](/path/to/image)

Caption _with_ Markdown markup
:::

These blocks are parsed as Markdown and the container markup (:::) merely adds a <div> with an appropriate system CSS class (not user customisable). The appearance as carousel or thumbnail gallery is controlled by CSS+JS and depends on the block not containing anything that disrupts the layout, such as text between images.

jace commented 6 months ago

The Attribution plugin upgrades a regular blockquote to add a source citation if the last line is prefixed with --. Needs to be ported to Python.

jace commented 6 months ago

Candidate syntax for details/summary tags, originally proposed here:

>-> Summary here
> Details here

Output:

Summary hereDetails here

Default output without the extension:

-> Summary here Details here