param: undefined for index page is not documented

[hayhaydz]

What version of astro are you using?

1.6.3

Are you using an SSR adapter? If so, which one?

None

What package manager are you using?

yarn

What operating system are you using?

Mac

Describe the Bug

I've brutally copied the title of a closed issue #1187 because it seems as though it fits that issues description. The problem is that when Astro builds a [...slug].astro file with a slug of index that is stored under the pages directory it will build as so /index/index.html instead of the expected outcome of /index.html, a temporary solution is to use this in the build configuration:

build: {
  format: 'file'
},

For my particular case I'm working with a CMS and I'm retrieving all of the available pages slugs and ids but I also took the above mentioned closed issue's recreated CodeSandbox and used the latest version of Astro and could produce the same unexpected result.

Link to Minimal Reproducible Example

https://codesandbox.io/s/crazy-bouman-2fi6eu?file=/src/pages/%5B...id%5D.astro

Participation

• I am willing to submit a pull request for this issue.

[matthewp]

I would kind of expect param: '' to work here. I would never expect 'index' to be interpreted as a non-subfolder route. https://stackblitz.com/edit/github-9xqq8p?file=src%2Fpages%2F[...id].astro&on=stackblitz

[JerryWu1234]

I would kind of expect param: '' to work here. I would never expect 'index' to be interpreted as a non-subfolder route. https://stackblitz.com/edit/github-9xqq8p?file=src%2Fpages%2F[...id].astro&on=stackblitz

I want to fix this bug, so I want to confirm this question with you. If I set another id, We are interpreted as a non-subfolder router? right?

[MoustaphaDev]

@matthewp I don't think this problematic though since we can already do that by passing in undefined, it's a nice to have in my opinion, we can just document that.

[JerryWu1234]

@matthewp I don't think this problematic though since we can already do that by passing in undefined, it's a nice to have IMO, we can just document that.

What’s IMO?

[MoustaphaDev]

@matthewp I don't think this problematic though since we can already do that by passing in undefined, it's a nice to have IMO, we can just document that.

What’s IMO?

Sorry, edited!

[matthewp]

Ah, yeah so if undefined does it then we should document that case. Going to transfer this issue over to docs.

[sarah11918]

Hi all! Picking this up in Docs!

I know we show using undefined to create an index here, and again provide a more full example where it's meant to illustrate an index page (without explicitly saying index page).

The exact text we have around the examples is:

(Setting the rest parameter to undefined allows it to match the top level page.)

It would be great if @hayhaydz @MoustaphaDev or anyone else could weigh in on whether we need to make this line a bit more explicit, e.g.

(Setting the rest parameter to undefined allows it to match the top level page, and can be used to create an index page.)

Or maybe PR a suggestion yourself! ;)

[delucis]

I do like that second version @sarah11918!

I might suggest a formatting fix too: move that text to it's own dedicated paragraph to make it a little more obvious. Then we can even mix it up if we like:

Want to create an index page? Seeing the rest parameter...

[hayhaydz]

Hey,

I'm very new to this open source world so am a little out of my depth but my suggestion would be to add something like this to the code block above. Maybe also including the second line that you suggested as well.

---
export function getStaticPaths() {
  return [
    {params: {path: 'one/two/three'}}, // /sequences/one/two/three
    {params: {path: 'four'}}, // /sequences/four
    {params: {path: undefined }} // /sequences/index.html
  ]
}

const { path } = Astro.params;
---
...

This approach on the code block needs a little work because it's a little inconsistent. i.e it'd be more consistent if they all showed an index.html file in the path, or maybe the block from right at the top of the page could be used here like so.

/sequences/one/two/three -> mysite.com/sequences/one/two/three/index.html
/sequences/four -> mysite.com/sequences/four/index.html
/sequences -> mysite.com/sequences/index.html

Or mix them both together, I'm not sure maybe you guys have some better ideas. I just think it needs to be more than a line of text.

---
export function getStaticPaths() {
  return [
    {params: {path: 'one/two/three'}}, // /sequences/one/two/three -> mysite.com/sequences/one/two/three/index.html
    {params: {path: 'four'}}, // /sequences/four -> mysite.com/sequences/four/index.html
    {params: {path: undefined }} // /sequences/four -> mysite.com/sequences/index.html
  ]
}

const { path } = Astro.params;
---
...

[MoustaphaDev]

I think this deserves an example of its own. Something like this:

---
export function getStaticPaths() {
  return [
    {params: {path: 'one/two/three'}},
    {params: {path: 'four'}},
  ]
}
const { path } = Astro.params;
---
...

This will generate /sequences/one/two/three and /sequences/four.

You can also set the rest parameter to undefined to allow it to match the top level page(i.e index page in the same level)

---
export function getStaticPaths() {
  return [
    {params: {path: 'one/two/three'}},
    {params: {path: 'four'}},
    {params: {path: undefined}}, // this will create an index page at this level
  ]
}
const { path } = Astro.params;
---
...

Now this will generate /sequences/one/two/three, /sequences/four, and /sequences

[veesahni]

Somewhat related: pagination also works using this undefined value.

Currently, docs only mention pagination in the form of [page].astro, but a sentence mentioning that using rest params in form of [...page].astro results in different behavior would be helpful. more details here: withastro/roadmap#385

[sarah11918]

It sounds like @hayhaydz, @MoustaphaDev and @veesahni all have some good ideas for content on this page!

If someone is willing to pick this up in a PR and capture these ideas there to get us started, we can move this disucssion there... it doesn't have to be perfect! Once a PR is made, we can edit/refine it.

I'm going to add the help-wanted label so that anyone in the community knows they can pick this up and get us started, too!

[sarah11918]

I'm closing this because I think these suggestions have been incorporated into our routing page! 🥳

Feel free reopen or create a new issue that relates to the current page in docs if you find anything!