Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support for content layouts in Markdown #1981

Draft
wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

Support for content layouts in Markdown #1981

wants to merge 6 commits into from

Conversation

jace
Copy link
Member

@jace jace commented Feb 28, 2024

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
Copy link
Member Author

jace commented Feb 28, 2024

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:

  • #id is rewritten to #md:id, inserting an md: namespace prefix
  • .class is rewritten to .md--class or (if valid) .md:class (may need escaping to .md\:class in CSS syntax)
  • Other attributes (attr=value syntax) are restricted or disabled. Image tags may need to allow size and width

@jace
Copy link
Member Author

jace commented Feb 28, 2024

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
Copy link
Member Author

jace commented Apr 16, 2024

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
Copy link
Member Author

jace commented Apr 30, 2024

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant