When a certain page in my documentation becomes very long over time, I want to break it into multiple subpages (this is possible today) while keeping the original URL (this is not possible today) so I don't break people's bookmarks and don't make search engines angry.
Example:
I have the following structure:
What is my project? -> example.com/what-is-my-project.html
Using my project -> example.com/using-my-project.html
Contributing to my project -> example.com/contributing.html
After some time, the page "Using my project" becomes too long for a single page and I split it into multiple pages:
What is my project? -> example.com/what-is-my-project.html
Using my project
Using my project intro -> example.com/using-my-project/intro.html
Contributing to my project -> example.com/contributing.html
Notice that the example.com/using-my-project.html URL disappeared. That means bookmarks people made became broken, and search engines are also confused because they lost the original url and have to find the new ones — this makes it harder to find.
Proposed solution:
To fix this, I'm proposing two technical changes:
Change 1: Allow folders to have pages as well
I want to be able to do this:
Name: Using my project
Dir: using-my-project
File: using-my-project <- this
Topics:
- Name: Installation
File: installation
...
Change 2: Generate pages as directories with index.html
This doesn't need to be the default behavior.
Right now, building the documentation works like this:
When a certain page in my documentation becomes very long over time, I want to break it into multiple subpages (this is possible today) while keeping the original URL (this is not possible today) so I don't break people's bookmarks and don't make search engines angry.
Example:
I have the following structure:
-> example.com/what-is-my-project.html-> example.com/using-my-project.html-> example.com/contributing.htmlAfter some time, the page "Using my project" becomes too long for a single page and I split it into multiple pages:
-> example.com/what-is-my-project.html-> example.com/using-my-project/intro.html-> example.com/using-my-project/installation.html-> example.com/using-my-project/running.html-> example.com/using-my-project/upgrading.html-> example.com/contributing.htmlNotice that the
example.com/using-my-project.htmlURL disappeared. That means bookmarks people made became broken, and search engines are also confused because they lost the original url and have to find the new ones — this makes it harder to find.Proposed solution:
To fix this, I'm proposing two technical changes:
Change 1: Allow folders to have pages as well
I want to be able to do this:
Change 2: Generate pages as directories with index.html
This doesn't need to be the default behavior.
Right now, building the documentation works like this:
Which gives me these two URLs:
I propose to change it to:
Which would give me these two URLs:
Applying this proposal to the example above
I have the following structure:
-> example.com/what-is-my-project/-> example.com/using-my-project/-> example.com/contributing/After some time, the page "Using my project" becomes too long for a single page and I split it into multiple pages:
-> example.com/what-is-my-project/-> example.com/using-my-project/<- it is still there!-> example.com/using-my-project/installation/-> example.com/using-my-project/running/-> example.com/using-my-project/upgrading/-> example.com/contributing/Notice that the "Using my project" page still exists and has the same URL. People's bookmarks keep working and search engines are happy.
Positive side effect: breadcrumbs work better
Going to the "Using my project / Running" page in the first example, the breadcrumbs would look as follows:
If I click on "Using my project" in the breadcrumbs, I get to the "Using my project / Intro" page, getting the following breadcrumbs:
However, in the new example, I would get to:
... which looks better to me.
Does this proposal sound reasonable?