Consider re-organizing the current default template

[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:

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

[jovyntls]

IMO users who are looking looking for a component showcase can be directed to the DG's "Using components" or "Syntax cheatsheet" pages, so it may not be necessary to add a tutorial or explain how the components can be used templates. Doing so might also incur more future maintenance cost (i.e., we'll need to look out for changes in our DG and the templates whenever a component is updated). Maybe including a prominent link to the above-mentioned DG sections might be useful instead?

My view of the templates is:

• minimal: "I want to get started from scratch and set things up myself"
• default: "I want to get started common features bootstrapped (like sitenav, pagenav, etc)"

[tlylt]

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.

The main purpose of the template, seems to me, is for starting a new project. See here.

Doing so might also incur more future maintenance cost (i.e., we'll need to look out for changes in our DG and the templates whenever a component is updated).

Very valid point. I think we should only keep the core set of templates, in the main repo, and explore ways to include templates in a separate repository, to avoid coupling. The downside of creating a separate repository for templates is the maintenance cost, so that's probably something good to consider, but not urgent and low priority.

My suggestion would be:

• a better organization of the content in our default template, perhaps including a few explicit links to our user guide to create more visibility. While doing so, we should keep it simple.
• think about how to showcase the functionalities of MarkBind, perhaps by building a couple of "tutorial" websites serving different purposes. They need not be included in this main repo, but we can link them in our "showcase" page to give some inspiration to potential users.

[lhw-1]

Thanks @jovyntls and @tlylt for the discussion!

IMO users who are looking looking for a component showcase can be directed to the DG's "Using components" or "Syntax cheatsheet" pages, so it may not be necessary to add a tutorial or explain how the components can be used templates. Doing so might also incur more future maintenance cost (i.e., we'll need to look out for changes in our DG and the templates whenever a component is updated).

My initial thought was to have a tutorial template that showcases only the basic MarkBind features (so not an exhaustive list - since users can refer to the User Guide if need be). But I fully agree that it would bring about additional maintenance cost!

The main purpose of the template, seems to me, is for starting a new project. See here.

Sorry, I don't think I managed to fully explain the discrepancy that I found 😅

The discrepancy is from this description, from the above link: "Default template if --template is unspecified. Filled with MarkBind features to guide you to author better content." As mentioned by @jovyntls, components like siteNav and pageNav are definitely perfect for guiding the author and making it more convenient - but the rest of the contents (e.g. the panel and the blockquote components) don't really serve the same purpose, since they will be overriden when the user converts the site anyway. I couldn't think of any other reason for these in the default template other than to showcase some of MarkBind components, which is why I concluded that showcasing the presentation components (aside from siteNav and pageNav) was one of the goals of the default template at the moment.

(I couldn't find any specific issue / PR with discussions on why these were in the default template to begin with)

---

Maybe including a prominent link to the above-mentioned DG sections might be useful instead?

My suggestion would be: a better organization of the content in our default template, perhaps including a few explicit links to our user guide to create more visibility. While doing so, we should keep it simple.

Thanks again for the suggestions! I think this is the best way forward - we will keep the current set of templates, but for the default template, we can remove the components that would be overriden anyway when --convert is used with the template (so we will keep the siteNav and pageNav but remove the panels and blockquotes, for example).

If anyone has suggestions / alternatives (e.g. if you think there is merit to leaving the content there), then we can discuss that further 👍

In the meantime, I think that in place of the content in index.md, we can include links to the user guide and the dev guide. In fact, I was wondering if we can use the Main page or the Authoring Contents page as the default template (or at least model the template's index.md based on these pages if we don't want to directly use them so as to avoid coupling).

My suggestion would be: think about how to showcase the functionalities of MarkBind, perhaps by building a couple of "tutorial" websites serving different purposes. They need not be included in this main repo, but we can link them in our "showcase" page to give some inspiration to potential users.

Definitely something to consider! We can add a set of pages to the user guide (perhaps something similar in structure to our Onboarding Bootcamp in our developer guide)?

For some context (just to be clearer), there is a difference between a quick start, a feature overview, and a tutorial, even though they may seem to have overlaps at times for static site generators. To illustrate with examples, Gatsby has separate pages / sets of pages for their quick start, which shows the installation process; their feature overview, which is a simple list of features available; and their tutorial, which is a lot more detailed and step-by-step as compared to their quick start. Hugo includes the quick start as part of their "tutorial" pages. Jekyll also separates quick start and tutorial. So there is definitely precendent for separating these sections explicitly.

In comparison, for MarkBind, we have the quick start and the feature overview, but not a tutorial. The suggestion here is that we build a similar kind of tutorial for MarkBind! Of course, it is more of a nice-to-have and not urgent, but nonetheless, I think it should be highly useful for new users if written well.

I think we should only keep the core set of templates, in the main repo, and explore ways to include templates in a separate repository, to avoid coupling. The downside of creating a separate repository for templates is the maintenance cost, so that's probably something good to consider, but not urgent and low priority.

I think this is an excellent idea! Agreed that this is definitely low priority and not urgent, though. Perhaps we can see if this becomes worth considering in the future?

[tlylt]

TL;DR

Potential TODOs

• Adjust the statement in https://markbind.org/userGuide/templates.html if necessary
• Update the index.md page of the default template with similar content from https://markbind.org/userGuide/authoringContents.html
• Create a set of tutorials

---

The discrepancy is from this description, from the above link: "Default template if --template is unspecified. Filled with MarkBind features to guide you to author better content." I couldn't think of any other reason for these in the default template other than to showcase some of MarkBind components, which is why I concluded that showcasing the presentation components (aside from siteNav and pageNav) was one of the goals of the default template at the moment.

I get what you mean now. I would think the sentence "Filled with MarkBind features to guide you to author better content" is just a generic sounding statement. If you feel that it over promises, we can make a PR to update it to something like "Fill with essential MarkBind features such as ... "

I was wondering if we can use the Main page or the Authoring Contents page as the default template (or at least model the template's index.md based on these pages if we don't want to directly use them so as to avoid coupling).

I like this suggestion, feels like a good introduction page.

In comparison, for MarkBind, we have the quick start and the feature overview, but not a tutorial. The suggestion here is that we build a similar kind of tutorial for MarkBind! Of course, it is more of a nice-to-have and not urgent, but nonetheless, I think it should be highly useful for new users if written well.

Related to recipes in #835

[lhw-1]

Thanks @tlylt for the concise summary!

I have started a PR (#2225) to address the first two points of the TODOs above. Once this PR has been addressed (closed or merged), we can consider opening a new issue for creating a new set of tutorials - I feel like it deserves its own discussion separate from this issue.

[lhw-1]

#2225 has been merged, and the remaining task is to create a set of tutorials for MarkBind. I will update the issue title and description to reflect this! open a new issue as I mentioned above 👍