Description
I'm submitting a...
[ ] Regression
[ ] Bug report
[x] Feature request
[ ] Documentation issue or request (new chapter/page)
[ ] Support request => Please do not submit support request here, instead post your question on Stack Overflow.
Current behavior
At the moment there are tons of Angular components dedicated for each markdown page. The components do not serve any further purpose, they just exist to enable routing and render the HTML template. There are a few minor exceptions:
Not quite sure why these components still contain properties:
- MixinComponents
- SchemaStitchingComponent
- CustomTransportComponent
That would definitely need to be refactored with my proposed changes:
- WhoUsesComponent
Expected behavior
This approach is highly inspired by how angular.io
serves its documentation.
Markdown Compilation
All the src/app/pages/*
components should be removed. The markdown files should be compiled into a static folder e.g. src/generated/docs
, taking its initial folder structure into account. Therefore e.g. content/cli/overview.md
will be compiled to src/generated/docs/overview.html
.
Route Handling
A custom RouterHandlerServce
could then load the HTML files dynamically from the static folder e.g. http://doc.nestjs.com/cli/overview
will request http://doc.nestjs.com/generated/docs/cli/overview.html
and render it in a BaseComponent
.
Angular Components inside compiled Markdown Files
The generated markdown files still depend on Angular Components/Directives such as appAnchor
app-tabs
etc. We still could make use of these components by converting them to native custom elements. angular.io does the same thing here.
What is the motivation / use case for changing the behavior?
Why jump over these hoops you may ask? Here are some reasons why this change would be useful:
-
Easier to contribute
It is confusing as a user if you need to add a new documentation page. You would have to add a markdown page incontent/
and then insrc/app/pages
and also attach it to the routing. -
Easier to make changes
SEO or general improvements could be changed by editing the one component, which loads in all the compiled markdown pages. (BaseComponent
) -
Faster
Less to bundle and less to load on the initial request. Lazy loaded by design -
Useful for the future API docs
The API docs require a dynamic routing system anyway. The current implementation just dynamically routes everything afterdocs.nestjs.com/api/*
similar as described in Route Handling. If this proposal gets accepted, the dynamic router could be applied to all routes.