[Feature] Category and Page combined

[parliament718]

Description

Is it possible to make a category also be a page? I could not find a way in the documentation but this seems like a common use-case.

As an example of what I mean, see these docs

Notice "Settings >" is a collapsible category, but clicking on it not only expands it but also goes to a Settings page. How can this be achieved?

Proposed solution

Perhaps can allow a "parent page" option in place of the "category" option:

import {NgDocPage} from '@ng-doc/core';
import ParentPage from '../ng-doc.category';

const ChildPage: NgDocPage = {
    title: `ICEBERG`,
    mdFile: './index.md',
    page: ParentPage, //<--- ChildPage can be a child of ParentPage. Should render in the menu as collapsible and have both as pages.
};

export default ChildPage;

alternatively, can have Category accept an mdFile:

import {NgDocCategory} from '@ng-doc/core';

const ParentCategory: NgDocCategory = {
    title: 'Algorithms',
    mdFile: './index.md',
};

export default ParentCategory;

Alternatives considered

I've tried making both a category and page in the same folder, but I haven't found a way to have the correct routes generated.

[skoropadas]

Hi, thank you for the ticket! Yes, you're right, it's not possible at the moment. When designing the library, I questioned whether this functionality was needed, but couldn't find good use cases, so I decided not to overcomplicate it. Similar pages often display a list of child pages, sometimes with icons added to them. I think this functionality would require good customization. Do you have any good examples of using such a feature that I could look into?

[parliament718]

thanks for the quick reply. A large portion of docs I've seen have this feature. See here, here, here, etc.

The other kinda annoying part about not having this is that we are forced to skip the category in the footer navigation:

Above you go from the "Introduction" page to the "Introduction" page of the next category. If this feature existed I could remove the nested Introduction page and have the introduction text on the category itself. This would also have the effect of fixing the footer navigation. Would go from "Introduction" to "Automation Platform".

Thanks for considering this.

[skoropadas]

Thank you for the example.

I think the most suitable option would be to add index.md to the category configuration.

I wasn't really sure about this feature because:

• For example, if you automatically render a list of child pages for each category, as some docs do, it creates the impression that it's a page just for the sake of having a page, because it's still faster to find the necessary page in the navigation panel than on such a page.
• Using introductions like the one you provided makes more sense. There might be an issue with understanding when a category is a page and when it's just an expander in the side menu for the user, because in fact, the only difference between them is a slight design difference. But I think it will be the responsibility of whoever creates the documentation rather than the library.

In any case, I will deal with this later because right now the ticket #24 is my priority. I need to finish it, and after the major release (I guess), I'll be able - to work on this feature.

[parliament718]

Thanks again!

Just want to add that this would probably require implementing keyword option for categories as well.

An issue I'm having with the current state is that if I want to link to the "Overview" page of a category (while categories lack an md file), I have to name both the Category and Page the same, which comes out looking bad in the menu:

but at least I can have a proper keyword link:

Otherwise it comes out like

It seems that keywords use the page title instead of the keyword itself, so that's another issue I'm having that would be solved by having categories have both mdFile and keyword.

Thanks

[skoropadas]

Got it, there will be a workaround in the new version to do what you want, because keywords definition will be moved to the markdown file and you also will be able to specify an additional title using yaml front matter syntax (for tabs).

But even if you don't have tabs, the keywords will try to use the title from markdown first and only if it doesn't exist use the title from the page configuration.

So in your case for the index.md of your category you will have something like this:

---
title: Overview
keyword: YourKeyword
---

The content

Anyways will see, because something can always change.

[akhileshThapliyal]

Hi @skoropadas,

Any idea when this feature would be available or is there any workaround to show the contents when a user selects the category?

Regards, Akhilesh

[skoropadas]

Hi @skoropadas,

Any idea when this feature would be available or is there any workaround to show the contents when a user selects the category?

Regards, Akhilesh

I have no estimated date, I'm gonna start thinking about this only after the NgDoc 18 release, there are many things that I need to think about. This feature literally means that we don't need ng-doc.category.ts files anymore because they are gonna have absolutely the same functionality as common pages.