Documentation improvements discussion

Issue type:

[ ] bug report [ ] feature request [x] documentation issue

TypeORM version:

[x] latest [ ] @next [ ] 0.x.x (or put your version here)

I am opening this issue to start a discussion about improving TypeORM documentation. I have created a repo using VuePress to make TypeORM documentation better and to demonstrate the benefits of this approach. I picked VuePress because it looks the most similar to the current design and is well supported.

Current problems:

• Docs are not SEO-friendly, for example when you Google search for TypeORM docs you only get typeorm.io landing page (no other pages are indexed) and docs on github that are hard to search. In VuePress each Markdown file is compiled into HTML that can be easily crawled and indexed by search engines.
• Docs are not searchable. Currently in VuePress example repo I am using vuepress-plugin-fulltext-search package that provides fulltext search using flexsearch library. Even though I have come across some problems using this approach, it is a lot better than no search. Recently I have found that Algolia provides free search for documentation and powers a lot of popular open source projects. For search, I think Algolia would be the best approach.

I would like to ask @pleerock and @imnotjames is such a change desirable and what everyone else thinks about this?

[DNature]

I don’t see why this wouldn’t work in both cases (setting it in the current repo like it is now or in a new one)…

Setting up a separate repo for documentation would be much better and easier to maintain and track issues.

I created the documentation of nature-ui using Nextjs, Markdown, and Algolia, and we can easily customise the codebase for this use case, so we have fewer things to worry about since the documentation is written in Markdown.

It’s accessible, SEO friendly and follows best practices.

@merfire @imnotjames @pleerock

[merfire]

I think Docsaurus 2 would be a great solution, it covers all the points I mentioned and also has built-in support for Algolia search, I think typeorm can easily apply and get free for open source projects Algolia package.