Documentation improvements, observations from a newbie

[CePeU]

Hi,

let me start and thank you for your project! In a way it works really great although it created me some grief/problems. I want to share my observations for you to considere and maybe improve your documentation as I currently experienced your documentation as a total newbie. All you will read will probably mark me as an idiot but newbies ARE idiots at least in the way of understanding how things tick.

I am on windows and my usecase is to export Obsidian MD markdown files which will hold my personal documentation in regards of setting up and configuring software (this now includes McDocs), coding snippets and general tips which I want to publish on github.

So I set up a toolchain to export those Obsidian markdown files and after some struggle and even extending an Obsidian module I am able to export all files into a local directory. Thats where McDocs takes over.

My goal was to be able to generate a static web site locally, review and correct it and then push/post it on github.

I ended up with mkdocs "getting started pages". I decided to use "readthedocs" as theme. Installation went well and the first example worked. I exported my markdown files and started mkdocs serve. I was able to navigate my website on localhost. Great ... well aside from the 404 error and the inability to show my first page. I reread the documentation and made sure my Index.md file was in the correct folder. Nothing worked. I learned how to push to gh-pages, I learned how to set up a action workflow. Nothing helped. You probably allready noticed what I did wrong?

1. PLEASE! Insert a sentence in the first page of getting started that your index.md file MUST start with a lowercase "i" !!!
   Your example works of course but this little detail drove me crazy.

2. Posting on github pages and directory depth have been the second obstacle. I did not realize for quite some time I need to use site_url: and I need to use it with the github PAGES URL. In hindsight it is obvious but a sentence where to find that URL or that it differs from the link you can copy from the main branch site which is the URL to clone your repository would also be helpfull.

3. A (short) step by step and more detailed example how to set up github/your local git directory and how to push to gh-pages would be great!

4. Readthedocs text - a small mistake which I did not yet check (well did not check what holds true):

"Readthedocs"
A clone of the default theme used by the Read the Docs service, which offers the same restricted feature set as its parent theme. Like its parent theme, only two levels of navigation are supported.
....
navigation_depth: The maximum depth of the navigation tree in the sidebar. Default: 4.

5. Readthedocs (standard?) theme does not seem to offer the ability to copy/paste code by button - so the mkfdocs version does not seem to be like its parent theme.
   --> But I am aware that this is something I probably still have missed - still trying to figure that out.

6. Building my first website folder I was totally disappointed that I could not navigate my website from the folder it was saved in. I allways landed in the folder and only saw the html file which I had to click again. This is probably one thing that every newbie will try after building the static site the first time.
   It would be helpfull to include on the getting started page a short mkdocs.yaml which will have the correct settings which I figured out should be site_url: "", use_directory_urls: false and plugins: [] (still need to test that). Yes there is a deploy your docs link! And I probably did not read diligently enought. But I truly missed it for a long time. Maybe a prominent colorfull note section would helped me. You know newbies and their new toys .. off they go experimenting.

I know probably most of this my own fault. This shall be no blame. It is my experience as a total newbie to mkdocs and it's documentation. In a week or two I probably will not even remember to have struggled ... but I did and so might others.

Thanks for your effort and your project!!!

[pawamoy]

Hey, thanks a lot for your feedback! This is greatly appreciated 🙂

So, let me try to highlight a few points which we could use to improve the docs:

• migration from obsidian: maybe we could add a small guide somewhere

• the site_url being required: it's already explained early in "Getting started", in a colorful callout, however maybe we could better explain what the value is supposed to be (the URL where your website will be accessible, not the repository URL, etc.)

• short guide for github pages: I think the "Deploying your docs" page already explains that well enough. It's basically just "clone your repository, enter it, run mkdocs gh-deploy". But maybe if we re-organized the docs a bit, we could have a How-to section with such step-by-step guides, with screenshots and all.

• I could not navigate my website from the folder it was saved in

  So, by default, MkDocs will use directory URLs, which I think is the right thing to do (and would just be a breaking change if we toggled it), but maybe we could do like other tools when they generate a first config file, and add commented out settings with their description. For directory_urls, it would mention that if you want to open the built site directly from your file explorer, you should set it to false. Or something like that.

Things that I think are not actionable:

your index.md file MUST start with a lowercase "i"

Unfortunately, if we were to clarify all such similar assumptions, the documentation would be riddled with those. Generally speaking, filenames are case-sensitive, so if the docs say "index", it is exactly "index", and nothing else 😕

Can't speak about the ReadTheDocs theme as I don't use it.

Thanks again for the feedback! I won't move this to a discussion yet, as we could forget about it there. If other maintainers agree to move forward with some items here, we could open a new issue for each, or simply manage them from this one.

[CePeU]

Hi thanks for your reply,

I will not make it a long thread just a few thoughts and clarifications in regard to your answer:

migration from obsidian: maybe we could add a small guide somewhere

This would really be great and helpfull but I concede it also might be out of scope. There are after all a few pits and specialties to fall into which are obsidian specific. For example the export plugin I use has the ability to put all images in one folder and adjusts the exported link to (../imagedirectory). For MkDocs to work I needed to adjust all exportet filepaths to (../../imagedirectory). I assume this is due to the fact that I put all files in a doc directory. Incidentally that is the reason I enhanced that plugin with a regex capability. (But while I figured out how to set up a toolchain to change the TypeScript I have as of now not yet any clue how to build the module on github and publish it there ...)

the site_url being required: it's already explained early in "Getting started", in a colorful callout, however maybe we could better explain what the value is supposed to be (the URL where your website will be accessible, not the repository URL, etc.)

Well I got it that it has to do with the site url (even though I was not sure if if needs to end with URL/docs. So in this case it was kind of a github "specialty" that I choose the wrong URL at first. But I think a large part of users might try to publish to github and it is a good example anyway to show what needs to be done.

short guide for github pages: I think the "Deploying your docs" page already explains that well enough. It's basically just "clone your repository, enter it, run mkdocs gh-deploy". But maybe if we re-organized the docs a bit, we could have a How-to section with such step-by-step guides, with screenshots and all.

Yes also out of scope but it would be really nice. Surely a large part of my problems comes that I am still getting used to git. Also often explanations just tell you type this or that but not why.

Things that I think are not actionable:

your index.md file MUST start with a lowercase "i"

Ok in this one I strongly disagree at least .. in part. I understand your point but my advice would be to mention it at least once - on the "getting started" page. Maybe it is a Windows thing (and actually my experiences with linux made it finally click) but case sensitivity does not play a role there which was the reason it did not register on me. So just include your sentence on the getting started page (as this is where most noobs like me will start of) directly after mentioning index.md the first time:

"Filenames are case-sensitive, so if the docs say "index", it is exactly "index", and nothing else."

PS. One of the reasons I choose MkDocs was because of it beeing available on Windows AND Linux because it is python based. So I could learn one thing without any further hoops to go trough like with Jekyll or Hugo.

Ok thanks for having an open ear and thanks again for your effort you put into this project. A week ago I did not even know there are such sophisticated static web site builder (with those great themes also!)

[pawamoy]

Maybe it is a Windows thing [...] but case sensitivity does not play a role there

I believe filenames are case-sensitive on Windows too.

But I guess we could add a small note, right after the first screenshot in Getting Started. Something along the lines of "Unless explicitly stated otherwise, all file names and configuration options mentioned in the documentation are case-sensitive, so make sure to use the exact same names, for example index.md and not Index.md." I worry this has the potential to confuse readers though.

[squidfunk]

Great feedback. site_url and use_directory_urls are definitely settings that users often have trouble with. The problem is that building documentation to look at from your file system, and building documentation that you deploy are two different use cases. For the former, you must set use_directory_urls to false, but for the latter you will want to set it to true for prettier URLs. Also, site_url should really be required, because it already led to a lot of problems with file resolution in the past, but I'm not sure we can just change it at this point, because several users rely on it not being set (as I learned in prior interactions), which has side effects.

Disclaimer: I'm not a maintainer of MkDocs, but the maintainer of Material for MkDocs.

[mkusz]

@CePeU I know that my below answer is not fully related to your documentation issues, but take a look at my set of plugins, that was created especially to support Obsidan.md vault in MkDocs (with addition of Material for MkDocs) without the need to convert vault files. I know that documentation is not yet complete, but with each release it's getting better. My project can be found here.
PS. As for setup examples, project documentation is written in Obsidian.md, so you can take a look at all it in GitHub repo. If you have any questions, suggestions etc. you can find me on official Obsidian Discord server or just open a discussion in my project.