Split README into files located at /docs

[Rudxain]

Current plan

Big and "medium" (relatively) sections from the README.md will be moved to the /docs/ directory. Categories will have dedicated inner folders where files will be placed, other files will be placed directly at docs/ if they are their own "category". To preserve as much external links as possible, the index will be the same (almost, because inner links will be moved to indexes at their respective files) and the sections will have headings that, when clicked, redirect to the corresponding file. This is the reason why the branch name is readme-redirect

Links to more info

#1095 (comment)
mdn/content#17561 (comment)
#1095 (review)

Directory tree

This section is about the planned structure of the /docs repo tree. This is subject to change and open to suggestions. Indentation = nesting depth. # means it's a heading/section, not a file.

usage.md //should this be a folder?
	# Installation
	# `postinstall` message
	# CommonJS API
	# Babel
	# swc
	# Configurable level of aggressiveness
	# Custom build
compatibility-data.md //this includes "Supported engines"
features/
	ecmascript/
		object.md //prefixes seem useless in a folder
		function.md
		error.md
		array.md
		string and regexp.md //is this name good?
		number.md
		math.md
		date.md
		promise.md
		symbol.md
		collections.md
			# Map
			# Set
			# WeakMap
			# WeakSet
		typed-array.md
		reflect.md
		json.md
		global-this.md
	proposals/
		README.md //this contains the index and groups proposals by stage
		//each proposal is its own file, named in the same way as the files in `/packages/core-js/proposals/`
	web-standards/
		structured-clone.md
		base64-utility-methods.md
		set-timeout and set-interval.md
		set-immediate.md
		queue-microtask.md
		url.md
		dom-exception.md
		dom-collections.md
	iteration-helpers.md
missing-polyfills.md

Related Issues

Fixes #1053

Etc

Other stuff that this PR does is fix some typos and minify URLs

[Rudxain]

Wait, I realized a problem. Any link that points to a nested link will break unless that link has its own dedicated file. I thought it would redirect to the parent, but the link only contains info about the inner entry, not the outer one

[Rudxain]

@zloirock before proceeding any further, how should the directory tree look like? I need to know which sections deserve their own files, and which "multi-sections" should be grouped in single files. I also need to know when to create inner folders to group multiple files instead of having them on the outer folder

[Rudxain]

I'll try to preserve as much links as possible, so lots of files will be created. I'll put all ECMAScript files into an ECMAScript/ folder, and remove all the prefixes because they're redundant

[zloirock]

In my vision, on each page should be:

• A kind of header, maybe with a logo, for understanding what it's a part of core-js project and, mainly, it should describe what the page contains.
• A full index and links to neighboring pages.

I think that docs should contain a directory tree by categories, at least different directories for usage and polyfills.

I think that pages should contain more than, for example, now I see at Supported engines.md - it should be joined with related parts of docs.

As you can see in #1053 (comment), the root README.md should still contain all current anchors, but they should contain links to those docs.

[Rudxain]

Ok, I'll try doing that. But for now I'll "build the base" first, to make it easier to manage

[Rudxain]

I noticed there's lots of absolute URLs in the links. I'll make them relative, to minify files, and make the links "adaptive" to forks of this repo branch

[Rudxain]

I forgot that this file was still unfinished. Sorry. I'll finish it now

[zloirock]

@Rudxain I'm sorry that tris PR still is not merged. It's not because I'm ignoring it or have no time to review it. Looking at the result, I'm still not sure that now it's better than the current monolith - users can be confused or get lost. I'm thinking about adding proper indexes / navigation to it, but I'm still unsure about the best approach. Maybe even a statical site generation from markdown could be better.

[Rudxain]

I'm sorry that tris PR still is not merged. It's not because I'm ignoring it or have no time to review it.

It's fine, don't worry.

Looking at the result, I'm still not sure that now it's better than the current monolith - users can be confused or get lost. I'm thinking about adding proper indexes / navigation to it, but I'm still unsure about the best approach. Maybe even a statical site generation from markdown could be better.

I partly agree. Maybe we should use GH-Pages instead? Other repos use that approach. It's more flexible because we can add a nav-bar and a burger-menu. (I currently have no idea how to implement a good-quality nav-bar and burger-menu, I'll need to learn that)

[zloirock]

Sure, in the case of static site generation most likely will be used GH-Pages - and now it's already used for core-js-compat tests (but without Markdown). If you mean Jekyll - it's one of the options which I am considering.

[Rudxain]

Superseded by #1221

I won't delete readme-redirect, until #1221 is merged. This is an exception to my rule of deleting branches and forks ASAP