nestjs
Remove `src/app/pages/*` components
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 in
content/and then insrc/app/pagesand 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 after
docs.nestjs.com/api/*similar as described in Route Handling. If this proposal gets accepted, the dynamic router could be applied to all routes.
I like the idea :) Whatever makes it easier to scale & contribute in the future, sounds great. The current solution is a workaround anyway - I moved everything to markdown, but I didn't have enough time to come up with a more maintainable solution for routing & ng components.
