Dealing with conflicts between “/blog.html” and “/blog/index.html” in ablog

When I was building a blog site using ablog, both /blog.html and /blog/index.html were generated in the output after the build, and there were situations where I was confused about the handling of URLs and link behavior. This article summarizes the causes and solutions.

Problem occurrence situation

Using Sphinx + ablog with the following configuration:

• Create blog/index.rst and define your own blog top page

• conf.py setting is blog_path=blog (default value)

Building in this state will generate the following two HTML files:

• /blog.html (all article list page automatically generated by ablog)

• /blog/index.html (Build result of blog/index.rst that I created)

As a result, the following collision occurs:

• toctree link destination changes depending on whether it is /blog or /blog/index.html

• When accessing /blog on Netlify, /blog.html takes precedence

Cause and specifications

By default, ablog is set to blog_path = "blog", and in this case, /blog.html is automatically generated as a page listing all articles. On the other hand, if you create blog/index.rst, it becomes /blog/index.html.

In other words, the problem is that /blog.html and /blog/index.html exist separately at the same time.

How to deal with it

To keep your blog/index.rst and avoid conflicting with ablog’s output, it is effective to change the value of blog_path in conf.py.

For example, set as below:

blog_path = "blog/posts"

This results in:

• All article list page generated by ablog → /blog/posts.html

• Homemade blog/index.rst → /blog/index.html

This separates roles and avoids conflicts and confusion.

Note: URL priority order in Netlify

In Netlify, when accessing /blog, /blog.html is displayed with priority (static file-based rule). Therefore, it is possible to use netlify’s redirect settings, but it is smarter to correct the folder structure:

_redirects

/blog   /blog/index.html   200

summary

• The automatic output destination for ablog is determined by the blog_path setting.

• If you create blog/index.rst, it is safe to use a separate blog_path.

• Also note that /blog is treated as /blog.html in static output.

Article information

Post date:

2025-04-02

author:

Mr. Takagi

Utilize Ablog for blog operation   Get a free Linux environment with Oracle Cloud