Contrib Documentation - Child Pages

[stpaultim]

Today @jenlampton pushed a new content type to the docs site to allow creation of documentation for contrib modules. I wanted to be the first to give it a test drive.

I started with the multi-page documentation for the Domain Module currently in the project Wiki.
https://github.com/backdrop-contrib/domain/wiki

I added two pages. But, I'm not sure if we have a way to link these projects yet. There is a "project" field, which I assumed would help me link multiple pages for one project together, but I'm not sure if I was correct and/or how that works.

I would like to be able to create a single parent page for a project and then link child pages to that parent. Is that supposed to be working already and I'm missing it or does that require additional work?

Here are the two pages I created today as my initial experiment.

• https://docs.backdropcms.org/documentation/add-on-documentation/server-dns-configuration
• https://docs.backdropcms.org/documentation/add-on-documentation/domain

I'm very excited to see how this goes.

[yorkshire-pudding]

Someone suggested we should have term reference for linking module pages together, which seemed an excellent suggestion. But I think we also need a way to denote parent and child. I can see these pages and how they work with the menu which isn't good. Hopefully we can get this sorted quickly so we can

[jenlampton]

We need to keep these pages out of the main menu so they don't show in the left sidebar, but that makes setting up parent/child relationships a little harder.

I don't think we considered that any module would have more than one page of documentation when we talked about this last, but of course they would.

If we added a node-refernece field so that this page could reference any other contrib docs node, we could set up a view that would show this node's parent and all of it's children. Maybe we can add that into the sidebar as a little mini-menu? We would need to make sure the view on the landing page only shows pages with that field empty, but that should be easy enough... (famous last words) Let's give it a try :)

[jenlampton]

Here's what I was thinking:
https://docs.backdropcms.org/documentation/add-on-documentation/domain

[stpaultim]

Yeah, I'm not loving this first draft, but with some tweaks I think we can make this work - at least until a better idea emerges.

1. Should this just say "Modules". I'm not sure that Contrib is a meaningful word to folks new to Backdrop CMS. I notice that we do NOT use the word contrib on the main site for the modules section. Also, this is the documentation site, so I think having that in the title is redundant.

2. I think if there is a title on the top block, maybe we need a title on the main block - at least on pages with a top block, otherwise I think we are leaving an opportunity for confusion about the relationship between the blocks.

I'd love to see us just start keep tweaking this and not worry about getting it perfect right away. Seems to me that we've got a good start, until our next meeting to discuss this.

[stpaultim]

Just adding this for reference in terms of keeping terminology consistent.

[jenlampton]

Should this just say "Modules". I'm not sure that Contrib is a meaningful word to folks new to Backdrop CMS. I notice that we do NOT use the word contrib on the main site for the modules section. Also, this is the documentation site, so I think having that in the title is redundant.

Backdrop's offical word for modules, themes, and layouts combined is "Add-Ons" so I've updated it :)

I think if there is a title on the top block, maybe we need a title on the main block - at least on pages with a top block, otherwise I think we are leaving an opportunity for confusion about the relationship between the blocks.

I was thinking this too -- and the title is helpful for accessibily also. But if not "Documentation" what should it be?

[yorkshire-pudding]

Another thought is that the URL alias is too wordy. It has documentation twice. Perhaps instead it could be:
/documentation/add-ons/[module-theme-layout-template-name](/[sub-page])

[jenlampton]

I like that better!

…

On Tue, Mar 11, 2025, 1:15 AM Martin Price ***@***.***> wrote: Another thought is that the URL alias is too wordy. It has documentation twice. Perhaps instead it could be: /documentation/add-ons/[module-theme-layout-template-name](/[sub-page]) — Reply to this email directly, view it on GitHub <#248 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADBER46DNBZ5S5XNNV6ZYT2T2LTVAVCNFSM6AAAAABYP6NPAKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDOMJTGEYDCNZWGE> . You are receiving this because you were mentioned.Message ID: ***@***.***> [image: yorkshire-pudding]*yorkshire-pudding* left a comment (backdrop-ops/docs.backdropcms.org#248) <#248 (comment)> Another thought is that the URL alias is too wordy. It has documentation twice. Perhaps instead it could be: /documentation/add-ons/[module-theme-layout-template-name](/[sub-page]) — Reply to this email directly, view it on GitHub <#248 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADBER46DNBZ5S5XNNV6ZYT2T2LTVAVCNFSM6AAAAABYP6NPAKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDOMJTGEYDCNZWGE> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[stpaultim]

I was thinking this too -- and the title is helpful for accessibily also. But if not "Documentation" what should it be?

Despite it's disadvantages, we may not be able to rule out using Documentation or some form of the word in these block titles, at least until we find a better solution.

What is the second block?

It's the main navigation for the site for everything other than direct add-on documentation. Brainstorming (including some bad ideas):

• Main Navigation
• General Documentation
• Everything Else
• Directory
• Docs Menu

Of course, "Everything Else" does not work, because the Add-on block is only there for Add-on pages.

[jenlampton]

I kind of like Directory

[jenlampton]

Okay, I updated the URL alias, but instead of using the project type (module/theme/layout) I used the parent project. Because all project names are unique, we don't really need to distinguish the type, but I did find it helpful to know if a page is related to a specific project, for example https://docs.backdropcms.org/documentation/add-ons/domain/server-dns-configuration. Without domain in there you might think this was for a project named server-dns-configuration

[jenlampton]

I've added the sidebar titles and adjusted the CSS a little, I need to run but I know there is more work to do on the spacing for the menu! Just... later...

[bugfolder]

Tiny quibble: as in the main menu of BackdropCMS.org, shouldn't it be "Add-ons", not "Add-Ons"?

[jenlampton]

Yes, thank you!

…

On Tue, Mar 11, 2025, 2:49 PM Robert J. Lang ***@***.***> wrote: Tiny quibble: as in the main menu of BackdropCMS.org, shouldn't it be "Add-ons", not "Add-Ons"? image.jpeg (view on web) <https://github.com/user-attachments/assets/23e032ef-053d-4c6f-9c48-c0bfc768a752> — Reply to this email directly, view it on GitHub <#248 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADBER4UXLFWPBWNG6HP32T2T5K5TAVCNFSM6AAAAABYP6NPAKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDOMJVG44DCMBQGI> . You are receiving this because you were mentioned.Message ID: ***@***.***> [image: bugfolder]*bugfolder* left a comment (backdrop-ops/docs.backdropcms.org#248) <#248 (comment)> Tiny quibble: as in the main menu of BackdropCMS.org, shouldn't it be "Add-ons", not "Add-Ons"? image.jpeg (view on web) <https://github.com/user-attachments/assets/23e032ef-053d-4c6f-9c48-c0bfc768a752> — Reply to this email directly, view it on GitHub <#248 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AADBER4UXLFWPBWNG6HP32T2T5K5TAVCNFSM6AAAAABYP6NPAKVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDOMJVG44DCMBQGI> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[docwilmot]

Shouldn't the block containing the add-ons listing be below the "Directory" block? We have a thousand modules; eventually "Add-ons" will push "Directory" off the screen if people use this.