eucp-project / storyboards

Simple web application to show example use cases with some interactivity. (visitors via old url will be redirected to the website with new url)
https://eucp-project.github.io/storyboards
Other
6 stars 5 forks source link

(More) portable storyboards #58

Closed Peter9192 closed 2 years ago

Peter9192 commented 2 years ago

For content authoring, ideally the storyboards should be as simple as possible.

To this end I'd like to achieve the following:

1. Text (markdown) and images (or other static content) should live in the same directory.

By default, Nuxt Content splits them between the /content and the /static folder, which leads to a duplicated folder structure like so:

- /content
  - /story1
    - text1.md
    - text2.md
- /static
  - /story1
    - image1.png
    - standalone2.html

It would be much nice if this could be represented like so:

- /content
  - /story1
    - text1.md
    - image1.png
    - text2.md
    - standalone2.html

A long discussion about this can be found here: https://github.com/nuxt/content/issues/106. There is a workaround to achieve this, where all images should be loaded using a require call.

A complete story should live in a single (markdown) file

It would be much easier to author a story if it lived in a single file, as opposed to one file per panel as we currently have. So a story could look something like this:

---
- name: Story name
- author: Jane Doe
- trl: high
- tags:
  - CPM
  - Precipitation
---

# Panel 1
This is the introduction text that appears in the text box next to the main content

It can include any regular markdown syntax.

We need a way to mark the main image (or other content type) so we can separate 
it from the text panel in the front end. We could for example use a special HTML tag 
like so:

<MainImage src="story1/image1.png" />  

# Panel 2

<MainContent src="story1/standalone2.html" />

The first level  heading in this case marks the transition to a new panel.
There may be alternative ways to mark this, e.g. using three dashes
on a line surrounded by horizontal spacing:

---

# Panel 3
etc.

The presentation of our panels is very similar to slide decks. Tools like reveal.js, remark.js, or R's flexdashboard all use special slide separators (typically ---) to split the markdown into multiple sections before rendering it as HTML slides. Nuxt/Content doesn't do this; instead it just parses all content into a single syntax tree which is then converted to formatted HTML using the <nuxt-content> component. However, it is possible to add custom remark/rehype plugins to modify how the markdown is parsed. One such plugin could by remark-sectionize

Here's an issue in Nuxt/Content that basically proposes the same functionality.

Peter9192 commented 2 years ago

After several hours of try, fail, search, repeat I managed to get a minimal working version of something I'm quite happy with.

I like the syntax proposed by remark-directive. This leads to:

:::Panel{headline=Introduction image=intro.png}
## content for the side story
in plain markdown
:::

:::Panel{headline="Methods overview" image=concept.png}
etc.

Since nuxt/content is still using an older version of the unified/remark ecosystem, I had to use an older version (1.0.1) of remark-directive. The remark-plugin that I added to parse the syntax also follows the old version of the remark-directive example. I had to add my remark-plugin to the modules section in nuxt.config.js in order for it to work.

Now, each :::Panel directive is converted into a Panel component. I want to render all panels at once and toggle their visibility, as opposed to updating the content of the panels interactively.

Proof of concept in #57, will now work on porting everything to this new structure.

Peter9192 commented 2 years ago

Addressed in #57