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

(More) portable storyboards #58

Closed
Peter9192 opened this issue Jan 16, 2022 · 2 comments
Closed

(More) portable storyboards #58

Peter9192 opened this issue Jan 16, 2022 · 2 comments

Comments

@Peter9192
Copy link
Member

Peter9192 commented Jan 16, 2022

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: nuxt/content#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
Copy link
Member Author

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

Addressed in #57

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

No branches or pull requests

1 participant