Skip to content

Remove src/app/pages/* components #549

Open
@BrunnerLivio

Description

@BrunnerLivio

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 in src/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 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.

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions