#File structure

12 messages · Page 1 of 1 (latest)

snow barn
#

I have a following file structure

src/pages/
404.astro
games.astro
index.astro
socials.astro

What should I change to have it build it into

/index.html
/socials.html
/games.html
/404.html

instead of

/index.html
/socials/index.html
/games/index.html
/404.html

?

charred wyvernBOT
#

Hi @snow barn. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

To have Astro build your pages as /index.html, /socials.html, /games.html, and /404.html (instead of /socials/index.html, etc.), you need to set the build.format option to 'file' in your astro.config.mjs file.

Here’s how you can do it:

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  build: {
    format: 'file'
  }
});

With this configuration, Astro will generate .html files for each page route, matching your desired output structure. For example, src/pages/socials.astro will build to /socials.html instead of /socials/index.html Build Options.

Note:

  • Your 404.astro will always build to /404.html regardless of the build format Custom 404 Error Page.
  • If you use the 'file' format, consider setting trailingSlash: 'never' for consistent URL behavior, as recommended in the docs.
export default defineConfig({
  build: {
    format: 'file'
  },
  trailingSlash: 'never'
});

This will give you the flat .html file output you want.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@snow barn Kapa.ai is still learning and improving, please let me know how I did by reacting below.

snow barn
#

@charred wyvern if i do that

  build: {
    format: 'file'
  },

if i will make a file src/pages/folder/index.astro will it still make folder/index.html ?

charred wyvernBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Yes, if you set build.format: 'file' in your astro.config.mjs, then a file at src/pages/folder/index.astro will build to /folder.html (not /folder/index.html).

According to the documentation:

  • 'file': Astro will generate an HTML file named for each page route. (e.g. src/pages/about.astro and src/pages/about/index.astro both build the file /about.html)
    Build Options

So, both src/pages/folder.astro and src/pages/folder/index.astro will result in /folder.html in your output. If you want a nested /folder/index.html, you should use the default 'directory' format instead.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@snow barn Kapa.ai is still learning and improving, please let me know how I did by reacting below.

snow barn
#

@charred wyvern what if i want for file src/pages/about.astro -> about.html, but for src/pages/folder/index.astro into folder/index.html?

or maybe i actually want something else and i'm just trying to do something strange?

charred wyvernBOT
#

Let me check the knowledge base for you again. One moment! :books:

#

Based on the official Astro documentation, the output structure is controlled globally by the build.format option, which accepts three values: 'directory', 'file', and 'preserve':

  • 'directory' (default): Both src/pages/about.astro and src/pages/about/index.astro build to /about/index.html.
  • 'file': Both src/pages/about.astro and src/pages/about/index.astro build to /about.html.
  • 'preserve': src/pages/about.astro builds to /about.html, and src/pages/about/index.astro builds to /about/index.html (Build Options).

If you want:

  • src/pages/about.astro → /about.html
  • src/pages/folder/index.astro → /folder/index.html

You should use build.format: 'preserve'. This is the only mode that preserves the directory structure exactly as in your src/pages folder.

Example config:

export default defineConfig({
  build: {
    format: 'preserve'
  }
});

With this setting:

  • src/pages/about.astro → /about.html
  • src/pages/folder/index.astro → /folder/index.html

This matches your described goal (Build Options).

If you have further custom needs, such as mixing both behaviors for the same route (e.g., /about.html and /about/index.html), that is not supported by Astro’s current routing and build system. The output format is determined globally, not per-file or per-folder.

#

If you’re unsure about your structure, consider whether you need both /about.html and /about/index.html to exist at the same time. In most modern static site setups, either format is fine, but consistency is important for routing and SEO.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon: