Repository navigation
[DOC] Duplicate content in the docs #312
Description
As a newcomer to the project, I found very confusing that in the docs, in the "getting started" section we have the same tutorial for the hero component repeated twice as two different sections: https://djangocms-frontend.readthedocs.io/en/stable/tutorial/template_components.html and https://djangocms-frontend.readthedocs.io/en/stable/tutorial/custom_components.html - both sections could be merged into one.
Activity
marbru commentedon Oct 22, 2025
I started doing some cleanup of these sections in this PR: #317
Then I actually realized that they are not really duplicated, it's just that they build the same component in two very different ways. But a couple of issues were making things confusing at first sight.
First, the overloading of the word "custom frontend component" / "custom component": both template-only components and CMSFrontendComponent components are custom frontend components! The latter does not have a proper name, so we keep using the word "custom component" to refer to them, when this is a very generic name that applies to template components as well. I referred to them as "custom CMS frontend components" in the PR, but this IMO is still not clear enough. I propose they should be given a more specific name: perhaps "CMSFrontendComponents" or "form components".
Secondly both tutorials had an introductory text stating the benefits of custom frontend components, generically. And this was followed by an identical installation section, plus a "hero component" tutorial that, unless you look closely, you don't realize they are doing it with different approaches. So to a newcomer, it looks like they are duplicate tutorials indeed.
In the PR I have removed the generic intro text and installation instructions (installations now are only in the first tutorial, which has been renamed to "Installation and usage with built-in components"), and now have introductory text which specifically covers the differences with template/form components. The same hero code examples are kept, but hopefully now it's clear that we are building the same component with different implementations.
For further clarity, my proposal would be to properly give a more unique name to the "CMS frontend components" (the ones with a
cms_component.pyclass). I like "form components". This can be done in a followup PR perhaps.fsbraun commentedon Oct 22, 2025
Thanks very much, @marbru ! I appreciate the rigor and it would be great if we could use one word and only one word for one concept.
What do you think of:
CMSFrontendCompnent-based custom components (congruence of class and name)We can add "CMS" in front, but if so, probably for both. What do you think?
Maybe we can make a table somewhere in the intro to clarify the nomenclature and use?
marbru commentedon Oct 23, 2025
The problem with "frontend components" is that it is a generic webdev term... both built-in components, template components or even a tailwind blob can be referred to as "frontend components". But I guess if the name is already very stuck with the community then changing it to something very different might be too disruptive.
TBH I'm not a super fan of adding "CMS" in front, makes the names too verbose.
There's already a good intro clearly describing each type of component: https://djangocms-frontend.readthedocs.io/en/stable/tutorial/index.html but it is kinda hidden: you have to click on "getting started", which you might miss (I did at first). Perhaps this could be moved to the landing page for extra clarity.
And maybe simply changing the title of the tutorials:
So they are all "frontend components", it's just "some are built from templates and some from code"
Plus the rest of the cleanup done in the PR (specific tutorial intros and remove duplicate sections), would be enough improvement .
fsbraun commentedon Oct 23, 2025
When I use "frontend" I refer to the package djangocms-frontend...
We would still need a word for the three categories of components.
This might be a good compromise.
I like the proposed tutorial titles.
marbru commentedon Oct 24, 2025
In the landing page and across the docs the term "frontend components" is often used generically (mostly in introductory texts). Examples:
That's why I think the term is confusing for also naming the form-based components specifically. At least for newcomers.
I think the new names you suggested work! "form-based" is unique and descriptive, no room for confusion.
Guess this quote never gets old:
fsbraun commentedon Dec 29, 2025
Fixed in #317