Skip to content

Consider re-organizing the current default template #2214

@lhw-1

Description

@lhw-1

Please confirm that you have searched existing issues in the repo

Yes, I have searched the existing issues

Any related issues?

No response

What is the area that this feature belongs to?

Author Usability, Documentation

Is your feature request related to a problem? Please describe.

Currently, we have two templates available for the user to choose from: default and minimal. The minimal template is undoubtedly important, as it allows users to quickly create an almost-empty site that they can modify to suit their needs. Both the default and the minimal templates are useful for different situations when used in conjunction with markbind init --convert --template [TEMPLATE] as well. (i.e. I am not debating either template's situational utility)

An issue I want to discuss is that the default template currently contains a lot of filler content, such as:

image
image

Describe the solution you'd like

I believe that currently, the default template is trying to do two things: (1) Serve as a more detailed template as compared to minimal (e.g. a built-in siteNav), and (2) showcase some of the components that can be used in MarkBind. However, from what I can see, these two goals are targeted towards different kinds of users. (1) would be targeting more of users who are using the --convert feature to convert a pre-existing document into MarkBind (which is likely the majority of our users), and (2) would be for users who are new to MarkBind.

If the current default template wants to achieve (2), I believe that we need to be more informative with the components that are being showcased (e.g. PR #2165 shows one case of how the components in the default template are being showcased in a confusing manner). On the other hand, an argument can be made that this is not necessary, since most users will be using --convert anyway, in which case we should re-consider having these component showcases in the default template in the first place if they are not serving much purpose.

I can see four approaches:

  1. Keep the templates as they are - no changes required.
  2. Keep the component showcases in the default template, but add in better explanations for the features being showcased.
  3. Remove the component showcases from the default template, and create a new (third) template called tutorial that can showcase basic MarkBind-specific features with summarized explanations.
  4. Remove the component showcases from the default template, with no other changes.

I can see arguments for all of the approaches, so I'm curious to know what others think!
(Personally I am leaning towards 3 or 4)

Describe alternatives you've considered

No response

Additional context

No response

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions