Brainstorming revisions to how pages are defined

[jhelvy]

Description

I'm thinking about revising how pages are defined in surveydown. Right now we use fences like this:

::: {#welcome .sd-page}

Page 1 content here

:::

::: {#page2 .sd-page}

Page 2 content here

:::

This is a relatively straightforward approach and works well enough. But there are several things I'm not thrilled with. First, I don't like that you define the page id inside the {} using a # symbol. Like, when I look at ::: {#welcome .sd-page}, it's not immediately obvious to me that the page id is welcome. Second, this is a lot of syntax to remember. I almost never remember it myself and instead rely on copy-pasting the syntax or using sd_add_page(). Third, I don't like that you have to insert a closing fence. It seems like it should be obvious that a new page as started when you see the next page id defined. I suppose it could maybe be helpful, but on long pages you just see this ::: symbol floating around and it may not be clear what it's for.

What I was thinking as a potential alternative is to define a sd_page() function, much like how we use sd_next() to define next buttons. With a function like this, the same example as above would look like this:

```{r}
sd_page("welcome")
```

Page 1 content here

```{r}
sd_page("page2")
```

Page 2 content here

With this approach, the page id is more obvious as it's an argument to the sd_page() function. It's also much easier to remember how to start a new page. It's not perfect though. It doesn't look as elegant having to add a whole code chunk just to define a new page. And the nice thing about the fence is that it is visually distinctly different from everything else. With this sd_page() approach, it's another code chunk, which kind of blends in with everything else.

One other alternative I was thinking about was to use the --- approach like with xaringan slides. With that approach, it would look something like this:

---
id: welcome

Page 1 content here

---
id: page2

Page 2 content here

This is probably the cleanest looking approach, but it would require we build out a carefully crafted lua filter to insert page divs based on the --- symbol. It also would cause an error if the user ever tried to just directly render the Quarto file since the --- symbol I think might get confused with the initial yaml header.

I'm not sure if this is really worth pursuing or not. Does anyone else have any thoughts on a different / better way to define pages?

[pingfan-hu]

From my perspective, fence ::: is a built-in feature of quarto doc, so I think we can stay with it, but we can make it simpler.
Now our solution is:

:::{#page_id .sd-page}
Survey contents...
:::

But we may change to a simpler version:

:::{page_id}
Survey contents...
:::

So that we still use fences, but no need to do the hashtag and the .sd-page class.
We can implement this by editing our .lua filter.

I talked with Claude and got positive response. It says the .lua filter can have this function:

-- NEW FUNCTION: Transform simplified div syntax to .sd-page divs
function Div(div)
    -- Check if the div has a single identifier without classes
    -- This will match syntax like :::{welcome}
    if div.identifier and #div.classes == 0 then
        -- Keep the identifier and add the .sd-page class
        table.insert(div.classes, "sd-page")
        return div
    end
    return div
end

So that if the fences are already structured as {#page_id .sd-page}, it stays as it is, but if it's only {page_id}, it will be changed to {#page_id .sd-page}, so the good news is the old structure still works, and we don't need to modify extract_html_pages() in config.R, which is where we defined the .sd-page class as the identifier of survey pages.

This is just an initial idea. If we implement this, we gonna install it to test and debug, since .lua filter only functions when package is installed.

[jhelvy]

One good thing about using the fences is that they all just produce <div> tags. In fact, all 3 of these approaches will produce valid surveydown pages (divs with a clear id and the "sd-page" class):

::: {#page1 .sd-page}

Page 1 contents...

:::

::: {.sd-page id=page2}

Page 2 contents...

:::

<div id="page3" class="sd-page">

Page 3 contents...

</div>

So while ::: {#page1 .sd-page} is a lot to remember, it might be slightly easier to use ::: {.sd-page id=page1}, if only because you're assigning an id to the div more explicitly.

[pingfan-hu]

Yeah ::: {.sd-page id=page1} looks better.

[jhelvy]

Just putting down for the record that we decided (at least for now) to stick with the fences, but to modify the templates to the following structure:

::: {.sd_page id=page1}

Page 1 contents...

:::

::: {.sd_page id=page2}

Page 2 contents...

:::

This results in the same output as before where we had the format ::: {#page1 .sd-page}, but now makes the page id more explicit using the = sign, and also using an underscore in .sd_page instead of .sd-page for internal consistency with the rest of the package.