[Feature request] Cleaner and friendlier URLs

[awulkan]

Feature request

VuePress already has somewhat SEO friendly URLs in the sense that each page has the file name as the URL, but there's still some flaws. Vuepress shows the .html extension in the URL and it appends a slash on pages which causes inconsistencies. I suggest we get rid of this for a few reasons listed below.

TL;DR (if you don't want to read everything):
I want this:
mysite.com
mysite.com/blog
mysite.com/blog#title
mysite.com/blog/post
mysite.com/blog/post#title

Instead of this:
mysite.com
mysite.com/blog/
mysite.com/blog/#title
mysite.com/blog/post.html
mysite.com/blog/post.html#title

What problem does this feature solve?

1. Migrating to/from VuePress.
The vast majority of all popular static site generators or CMS don't use the extension in the URL nowadays. And if they do, it's not always a .html extension. This causes problems when migrating a website to or from VuePress since search engines like Google will treat the new URL path as a totally new page, causing lost search engine rankings.

2. Cleaner, shorter and easier to type.
mysite.com/blog/my-article vs mysite.com/blog/my-article.html
mysite.com/blog/my-article#title vs mysite.com/blog/my-article.html#title

3. Less inconsitencies.
For example, right now it looks like this for pages and posts:
mysite.com/blog/#title
mysite.com/blog/post.html#title

This is inconsistent. pages have a slash, posts don't. There is no reason for a page to have slash since it's practically not a directory of things. The only reason I assume its like that right now is for legacy reasons that are not valid anymore.

4. No more ugly workarounds.
Right now I have to put each markdown file in a separate folder and name the file index.md to get similar results. It still doesn't generate a proper URL though since it will add an extra slash at the end even for the pages.

What you get:
mysite.com/blog/my-article/
mysite.com/blog/my-article/#title

How it should look:
mysite.com/blog/my-article
mysite.com/blog/my-article#title

What does the proposed API look like?

I don't really know yet.

How should this be implemented in your opinion?

mysite.com/blog <- Directories. (without slash)
As I said previously, each "directory" is actually a page as well, so no slash is needed. It would also make the URLs more consistent across the whole site.
For example, Github doesn't use a slash:
https://github.com/vuejs
https://github.com/vuejs/vuepress
https://github.com/vuejs/vuepress/issues

mysite.com/blog/my-article <- Pages (without slash or extensions)

Maybe with the possibility of toggling between using extensions or not in some sort of global setting.

Are you willing to work on this yourself?**

I could try, but I can't guarantee it will be 100% bug free.

There has been talk about it previously in these issues, so it's definitely a wanted feature:
#78
#36
#270

And I think this structure looks good:
#78 (comment)

[awulkan]

Worked a bit on this today and have a really small proof of concept up and running.

It's a bit buggy, and I couldn't get the localization stuff to work properly, so I removed it temporarily. But as you can see, the URLs now look like this:

https://vp-urls.netlify.com
https://vp-urls.netlify.com/guide
https://vp-urls.netlify.com/guide/getting-started
https://vp-urls.netlify.com/guide/getting-started#global-installation

@ulivz Any thoughts? Is this something Vuepress could implement? I guess it would be a hundred times easier/faster for someone who knew the Vuepress internals to implement this properly, instead of my ugly hacks.

It appears that this change doesn't require many changes in the code, which is good. Maybe just 30 lines or so in total, mainly in the build.js and utils.js files.

[ulivz]

@awulkan Welcome to open a PR.

[ulivz]

Since I am busy working for plugin API, and also planning to release 0.11.0. so welcome to contribute for that if you want it to catch the last train of next release.😅

[awulkan]

I don't think I will be able to complete it in time for the next release. I'll take a look at it tomorrow again to see if I can make any progress. I just want to know if this is a feature that will be implemented if I complete it, otherwise I am kinda wasting my time. :)

[jakeg]

Any progress on this @awulkan or could you point me in the right direction?

[awulkan]

@jakeg Unfortunately I haven't had much time to work on this. Basically the main stuff happens in lib/build.js (renderPage function), lib/prepare/util.js (fileToPath function) and lib/app/app.js (beforeEach function).

I might have some time to continue working on it next week. The code I have so far is pretty messy so it wouldn't help you much.

[curvednebula]

Isn't it what permalinks (https://vuepress.vuejs.org/theme/#permalinks) are for? While I don't see this feature changes generated site URLs in any way.

[awulkan]

@lumarama Permalinks didn't exist when I created this issue. I haven't used Vuepress in a long time due to being busy with other things unfortunately. Maybe I can check it out when version 1.0 is released.

If anyone knows if permalinks solves this problem, then feel free to close the issue. :)

[curvednebula]

@awulkan no, I don't see permalinks solve the problem. Moreover, I don't see they affect structure of generated site at all. Probably we should indeed wait for 1.0.0. BTW: does anybody know when it will happen?

[zvinless]

Permalinks do change the structure of the generated site, e.g:
docs/about.mdwith a permalink of /about becomes /about/index.html instead of /about.html.

This makes it so you can access the page by going to yoursite.com/about/, but the Vuepress dev throws an error right now if you try to go to yoursite.com/about (without the trailing slash). Might look into that.

edit: #603 has relevant info

[ulivz]

Let's move #603 to continue.

[awulkan]

Is this really a duplicate of the issue you linked to? This issue suggest consistent and clean urls, the issue you linked to just suggest clean urls, without the consistency of the trailing slash.

What I'm suggesting is to have urls with the same structure as Github has.

But as long as there is a way for me to achieve this with the solution from the other issue then is ok to close this issue as a duplicate I guess. Or just say that it's not the direction you want VuePress to take.

[shigma]

@awulkan The features you want contain two aspects:

• /foo.md -> /foo (instead of /foo.html)
• /bar/readme.md -> /bar (instead of /bar/)

However, these two behaviors may conflict with each other in the following directory:

└─ docs
   ├─ foo.md
   └─ foo
      └─ readme.md

What did you think of this?

[awulkan]

@shigma I think that I would simply not create duplicate routes. Is there any reason for wanting two routes that are almost identical? Even if one of the routes had a slash, and the other didn't, it's considered really bad practice to serve completely different content depending on if a user entered a slash or not.

Anyway, I've moved on to Gridsome for the time being, since VuePress won't support routes without .html in version 1. And I don't know if I'll switch to VuePress when if they did support such routes, because Gridsome fits my needs much better.

VuePress is still an awesome project though. I just don't think it's for me.

Edit: Sorry, to answer your question I'd probably rather give a warning about conflicting routes, but I see that it's not the optimal solution. I guess there's no harm in having slashes for one of those routes, since I would just not personally create the readme.md file that results in the route with a slash on the end.

[nelson6e65]

I think that I would simply not create duplicate routes. Is there any reason for wanting two routes that are almost identical? Even if one of the routes had a slash, and the other didn't, it's considered really bad practice to serve completely different content depending on if a user entered a slash or not.

I agree with this; an ending slash should not determine which page to display. It's very confusing for end-user and developer can make a typo in a URL link and take the user to a different page by mistake.

But... Usage of / tells most of the servers to display a default index.html in that "directory" if exists. This is not controlled by VuePress. You should make a redirect/rewrite rule by yourself in your server to make that pretty urls.