Markbind init --convert improvements

kaixin-hc commented 2 years ago

Is there an existing issue for this?

[X] I have searched the existing issues

Any related issues?

Other suggestions for MarkBind init command #1782, #1844

Tell us about your environment

MacOS Monterey

MarkBind version

3.1.1

What did you do? Describe the bug

Created a repository with .md files (https://github.com/kaixin-hc/animal-behaviour-LSM1303) and ran markbind init --convert

Steps to reproduce

Clone my repository, navigating to the branch without MarkBind (https://github.com/kaixin-hc/animal-behaviour-LSM1303/tree/toTestInitOn), and run markbind init --convert. Or make your own repository with file names that have spaces.

Expected behavior

Site is created and all elements are natural and intuitive.

Actual behavior

Default files(the contents folder) are still created and included in the sitenav by default; since it is a conversion of an existing repo, you would expect these files not to be created and included
The sitenav does not work as expected (Files with spaces are not rendered correctly)
Instead of the default navigation sidebar name being "Template", it makes more sense for it to be something like "Contents"
Titles are not auto-generated for content pages.

Nits

Personally, I feel like the default brand image makes it look like there was an error in rendering the favicon, rather than a default placeholder being selected by default.
The auto-generated default.md file has a few blank lines after the navbar; I think most linters will flag this as an issue and we can do without them.

Anything else?

No response

ong6 commented 2 years ago

I agree with the points that you have raised. I believe that the convert feature is quite important since most new users would be using this to help generate a site from markdown files.

Default files(the contents folder) are still created and included in the sitenav by default; since it is a conversion of an existing repo, you would expect these files not to be created and included

I think there's an option to convert with a template? Does this still happen if you use the Minimal template?

tlylt commented 2 years ago

I agree with the points that you have raised. I believe that the convert feature is quite important since most new users would be using this to help generate a site from markdown files.

Default files(the contents folder) are still created and included in the sitenav by default; since it is a conversion of an existing repo, you would expect these files not to be created and included

I think there's an option to convert with a template? Does this still happen if you use the Minimal template?

Conversion with a template doesn't seem to be documented yet. I believe we worked on it in https://github.com/MarkBind/markbind/pull/1718

@kaixin-hc any reason the above draft PR was closed? 🤔

kaixin-hc commented 2 years ago

Conversion with a template doesn't seem to be documented yet. I believe we worked on it in https://github.com/MarkBind/markbind/pull/1718

@kaixin-hc any reason the above draft PR was closed? 🤔

I believe I fixed the issue in #1829 😅 I closed the PR because I accidentally added extra changes not related to #1718 in the branch, but thought it would be more useful to use the branch to PR #1829 instead.

Does this still happen if you use the Minimal template? The additional files are not created, but the CSS template is not created either.

tlylt commented 2 years ago

Conversion with a template doesn't seem to be documented yet. I believe we worked on it in #1718

@kaixin-hc any reason the above draft PR was closed? 🤔

I believe I fixed the issue in #1829 😅 I closed the PR because I accidentally added extra changes not related to #1718 in the branch, but thought it would be more useful to use the branch to PR #1829 instead.

I see, sorry I was referring to the official UG and didn't realize that this has been updated in the latest branch 😅

lhw-1 commented 1 year ago

To summarize, the changes that should be addressed / fixes that should be implemented are:

[ ] Remove default file generation if it is a conversion (Modify behavior of --convert - up for a discussion)
[ ] Properly render files with spaces for the sitenav (Improve file name parsing - might want to look into whitespace handling as a whole within MarkBind)
[ ] Auto-generate titles for new content pages (Parse file name as title - related to discussion in #2166)
[x] Consider modifying default favicon to be more on-brand (minor fix - a new separate issue was opened #2279)
[x] Change the sidebar name from "Template" to "Contents" (minor fix in default.md - addressed in #2278)
[x] Remove blank lines after the navbar in default.md (minor fix in default.md - addressed in #2278)

For the 3rd point, we can consider implementing auto-generation of titles for .md files specifically only when --convert is used, since for conversion from pre-existing documentation, it would be better on the user-end not to have to specify the title for every .md file (which can be quite a lot). We can even look into an extension where we allow users to specify the title generation behavior through a CLI flag on conversion (--verbose-title vs. --nonverbose-title or something along those lines?).

MarkBind / markbind