[Draft] Markdown Route Generation Proposal

[jonathantneal]

Markdown Route Generation Proposal

Astro should allow authors to express dynamic routes in Markdown files.

Example (src/pages/post/[id].md):

### Request

This will match a named segment of `id` with a value of `first-post`.

```js
export default [
  {
    match: { id: 'first-post' },
    props: { title: 'First Post', content: '<p>Not much to say.</p>' },
  }
]
```

### Response

This will generate a page rendered with Astro.

```astro
---
const { title } = Astro.props
const { groups } = Astro.request
---
<article>
  <h1>{title}</h1>
  <div>{content}</div>
  <p>Matched ID: {groups.id}</p>
</article>
```

Background

Astro supports file-based routing to generate URLs from paths in the pages directory, and it also supports dynamic routing to generate multiple URLs from a single file whose path includes named segments.

Currently, a dynamic routing file must export a getStaticPaths() function to generate URLs.

Example (src/pages/post/[id].astro):

---
/* imports */
import gql from 'graphql-tag'

/* consts */
const pass = 'password123'

const { ...params } = Astro.params

/* exports */
console.log(typeof gql, typeof pass, typeof params)

export async function getStaticPaths() {
  console.log(typeof gql, typeof pass, typeof params)

  return [
    { params: { page: '1' } },
    { params: { page: '2' } },
  ]
}
---
<pre>{JSON.stringify(params, null, '  ')}</pre>

Problem

Several things break down in the src/pages/post/[id].astro example:

• It is not how JavaScript works:
  • First, the second console.log inside getStaticPaths will log 'function', 'undefined', 'undefined'. The gql variable will be available while pass and params will not.
  • Second, the first console.log that is top-level will log 'function', 'string', 'object'. The ghl, pass, and params variable will all be available.
• It is not how URLs work:
  • In getStaticPaths, the author returns params, which are not URL params, but are actually named segments from the path.
  • Overloading params clashes with any future server-generated URLs that use actual params.
  • getStaticPaths intends to mirror NextJS but also returns props, which is not intuitive of getStaticPaths and does not mirror NextJS.
• It is very limited:
  • A single file using named segments can represent any extension, but the API can only return HTML.
  • Example: An author generates multiple JSON files from [id].json.astro, but Astro will only produce HTML.

In summary: Astro provides authors a convenient file-based endpoint to setup dynamic routing logic, but everything required of authors afterward is confusing and limiting.

Goals

• Provide authors an API to generate multiple URLs from dynamic routing files, without confusing URL params or overloading URL params that may be separately useful in the future.
• Provide authors an experience in JavaScript that is cohesive with JavaScript itself.
• Provide authors an ability to generate the file contents expected by their file extension.

Non-Goals

• Certain implementation details like API naming or argument shape that do not conflict with pre-existing www terminology.

Proposal

Astro should provide authors a way to create dynamic routes that is cohesive with file-based routing, established URL patterns, and Javascript itself.

This is possible when authors express dynamic routing in Markdown files.

• Handling Requests
  • Before, an exported function:

    ---
    export function getStaticPaths() {}
    ---

  • After, a heading:

    ### Request

• Matching Named Segments
  • Before, returning an object of params and props:

    ---
    export function getStaticPaths() {
      return [
        {
          params: { id: "first-post" },
          props: { title: "First Post", content: "<p>Not much to say.</p>" },
        },
      ]
    }
    ---

  • After, a codeblock exporting an object of match and props:

    ## Request
    
    ```js
    export default [
      {
        match: { id: "first-post" },
        props: { title: "First Post", content: "<p>Not much to say.</p>" },
      },
    ]
    ```

• Handling Responses
  • Before, a mix of Astro Frontmatter and HTML that is too complex to represent.
    • See src/pages/post/[id].astro (using Astro.request.params).
  • After, a heading and codeblock in Markdown (using Astro.request.groups).

    ## Response
    
    ```astro
    ---
    const { title, content } = Astro.props
    const { groups } = Astro.request
    ---
    <article>
      <h1>{title}</h1>
      <div>{content}</div>
      <p>Matched ID: {groups.id}</p>
    </article>
    ```

Pros:

• Markdown provides authors a quick, simple way to create dynamic routes in plain text.
  • Markdown has a strongly defined, highly compatible specification; CommonMark.
  • Markdown is widely supported by code editors, web-based interfaces, and third-party tooling.
  • Markdown has built-in mechanisms to express code blocks, and syntax highlighting equally supported.
• Allow authors to easily separate import statements needed for requests vs responses.
• Markdown makes it easy to communicate & collaborate on dynamic routes.
  • It’s easy to document the code, because it is Markdown.
  • Both requests and responses are found in clearly labeled sections with codeblocks.
  • All top-level 'gymnastics' illustrated in src/pages/post/[id].astro are resolved.
• Markdown could intuitively generate multiple types of content, should we wish to add that feature.

  ## Response
  
  ```js
  const { title, content } = Astro.props
  const { groups } = Astro.request
  
  export default JSON.stringify({
    title,
    content,
    matchedId: groups.id,
  }, null, '  ')
  ```

• Markdown could intuitively support server-generated responses, should we wish to add that feature.

  ## Request
  
  ```js
  const { title, content } = Astro.props
  const { headers } = Astro.request
  
  const hasLegitResponse = (
    headers.username === 'han@benslightsaber.ouch' &&
    headers.password === 'j0nes'
  )
  
  export default hasLegitResponse ? [ /* legit response */ ] : [ /* not legit response */ ]
  ```

Cons:

• It would be a big change to how routing is handled in Astro.
• It would be a big change to how most routing is handled in other frameworks.

Prior Art:

• apimd, which lets authors write APIs in Markdown and use them as mocks.

Open Questions

• How would other APIs be surfaced? Like pagination() or rss()?

Alternatives

Astro could allow authors to express dynamic routes in JavaScript files.

export function request() {
  return [
    {
      match: { id: 'first-post' },
      props: { title: 'First Post', content: '<p>Not much to say.</p>' },
    }
  ]
}

export function response() {
  return Astro.render`---
const { title } = Astro.props
const { groups } = Astro.request
---
<article>
  <h1>{title}</h1>
  <div>{content}</div>
  <p>Matched ID: {groups.id}</p>
</article>`
}

Pros:

• Uses JavaScript and 'looks' more like what previous frameworks have done.

Cons:

• Does not allow authors to document dynamic routing as easily.
• Does not allow authors to easily separate import statements needed for requests vs responses.

Questions:

• How would authors return Astro responses? HTML? JSON? RSS? Pagination?
• Would this use an Astro component rendering API?

[innermatrix]

I disagree with putting logic in Markdown by means of having a magic header that contains a JS section that contains logic. I think that the current separation of logic in frontmatter and content in content is clearer. I agree that the magicness of getStaticPaths and how it interacts with imports and locals is weird.

My counterproposal: add sections to frontmatter

--- staticPaths
// This section is used *only* forstatic Paths, works like you would expect
import {whatever} from "wherever";
const x = value;

function getStaticPaths() {
  // whatever and x both work in here
  return whatever.blah(x);
}
---
// This section is used *only* to generate individual pages, works like you would expect
import {whatever} from "wherever";
const y = value;

whatever.blah(y)
---

# Content

[jonathantneal]

Thanks for the feedback. How do you feel about the alternative, then, where Astro could allow authors to express dynamic routes in JavaScript files?

[innermatrix]

Two concerns with that:

• It seems counter to the general vibe of "more static analysis" that I am getting from other discussions taking place right now
• Given how common dynamic routing is, it feels weird for static routes and dynamic routes look dramatically different in source.

Another alternative that might be worth considering is to keep the content/layout in an astro file, but move routing decisions into an adjacent js file. For example:

something-routing.js:

export function request() {
  return [
    {
      match: { id: 'first-post' },
      props: { title: 'First Post', content: '<p>Not much to say.</p>' },
    }
  ]
}

something.astro:

---
const { title } = Astro.props
const { groups } = Astro.request
---
<article>
  <h1>{title}</h1>
  <div>{content}</div>
  <p>Matched ID: {groups.id}</p>
</article>`
}

Potentially could have an export const routing = "something-routing.js" in the astro file rather than relying on a convention.

In every case, the burden on the authors is that they have to learn a different convention; the new conventions mentioned so far are, to summarize:

• getStaticPaths unchanged: have to learn weird scoping rules as you described
• Markdown wrapping, as you proposed: have to learn to wrap astro in markdown for dynamic routed content (but fixes scoping) — side note, I think the apimd use case is different because you really are writing a document in that case)
• JS wrapping, as you proposed: have to learn to wrap astro in JS for dynamic routed content (but fixes scoping)
• Frontmatter sectioning, as I proposed: have to learn FM sectioning format (but fixes scoping, keeps everything in one file, and retains astro format ergonomics)
• Move only dynamic routing code into an adjacent file: have to learn the naming convention for routing JS file (but fixes routing, and retains astro format ergonomics)