It is difficult

[StefanSalewski]

One year ago, with Doks v0.5, we had a short tutorial. I think actually two, a tutorial and a quick start guide. With these, it was possible for me, as someone not being a professional web developer, to set up two simple pages, https://nimprogramming.com/ and https://nimprogrammingbook.com/. It was not easy, took me a few days, but it was possible. But my feeling is that for current Doks v1.x it is nearly impossible for me. Currently I try to do a page setup from scratch, which makes some sense because I have not too much content, and learning a setup from scratch is useful in case I would have to setup new pages. I try to remember the old tutorial instructions -- is that info still available, or would it be just useless for v1.x? From https://getdoks.org/docs/start-here/getting-started/ we can learn that "npm run create docs/guides/faq.md" can be used to add new pages. But what does this command do in detail? And how can I remove the old default content, or update content? And there is some advanced info, e.g. to use custom fonts. But from my memory there was much more to configure for Doks 0.5. I think the main landing page was a HTML file, which we had to customize. That file is not mentioned in the new documentation at all. And then there was a menu bar and a pull-down menu that we could create. I can not remember how it was done. Maybe reading the Hugo or Hyas documentation would help? Well, I will try to manage it somehow in the next few days, but currently I have not much confidence. Of course I know well that creating documentation is difficult and very much work. But I would hope that some smart web developer could create a tutorial for people like myself.

Best regards,

Dr. Stefan Salewski

[StefanSalewski]

The v0.5 documentation is still available at

https://web.archive.org/web/20230127062319/https://getdoks.org/

That might help me to remember, but I am unsure which parts are still valid.

And for the ""npm run create" call we get some detailed info when we call it without arguments -- seems to be a "hugo new" wrapper, which creates just a file with frontmatter, where we have to add markdown content.

And the main landing page is layouts/index.html. Initially I displayed it with the Linux less command, which displays the text only, hiding the HTML tags. But actually it is all there, perhaps working similar as in old days.

[h-enk]

But my feeling is that for current Doks v1.x it is nearly impossible for me. [..] Well, I will try to manage it somehow in the next few days, but currently I have not much confidence.

I'm sorry to hear that, but thanks for your feedback — it helps — and patience. Hopefully, to comfort you a little, things only work slightly differently for Doks 1.0 (as opposed to 0.5). The new docs are on the top of my list — see also Roadmap 2024 — I will be making some progress today

Documentation for older versions of Doks is not maintained, but is available as a static snapshot. Use these versions of docs if you are unable to upgrade your project, but still wish to consult guides and reference:

• unmaintained v0.5.0 snapshot

[StefanSalewski]

Thank you very much for your fast and kind reply.

And thanks for the link to the old v0.5 documentation, that helps me a lot to remember how I did all that one year ago.

Actually, I got some more confidence again that I will be able to update my pages. I found the deploy instructions https://gohugo.io/hosting-and-deployment/deployment-with-rsync/ that I used initially, I assume that they will still work for all-inkl.com.

In my view, the current documentation focused a lot on the upgrade from v0.5 to 1.x, but has not much info for a new install. As the upgrade is not that easy, I prefer a complete new install, and for new projects we would have to do a new install always. So documentation for a install from scratch is needed. My personal feeling is, that the documentation describes a lot of (advanced) details, but not that much the basics, and there is no strait path which beginners can follow. And users might have to consult Doks, Hyas, and Hugo documentation at the same time, which is a bit demanding.

I think what is mostly missing (or hard to find) is information that users have typically to customize the files layouts/index.html and config/_default/menus/menus.en.toml to customize the main page and the menu. And how to do it in detail. I guess that the file config/_default/config.toml needs customization as well, but that file is currently mentioned only in the upgrade guide, but not mentioned elsewhere.

[StefanSalewski]

One more tiny question: I do not fully understand the example grid layout in layout/index.html

  <section class="section section-md section-features">
    <div class="container">
      <div class="row justify-content-center text-center">
        <div class="col-lg-5">
          <h2 class="h4">Update content</h2>
          <p>Edit <code>content/_index.md</code> to see this page change.</p>
        </div>
        <div class="col-lg-5">
          <h2 class="h4">Add new content</h2>
          <p>Add Markdown files to <code>content</code> to create new pages.</p>
        </div>
        <div class="col-lg-5">
          <h2 class="h4">Configure your site</h2>
          <p>Edit your config in <code>config/_default/hyas/doks.toml</code>.</p>
        </div>
        <div class="col-lg-5">
          <h2 class="h4">Read the docs</h2>
          <p>Learn more in the <a href="https://getdoks.org/">Docs</a>.</p>
        </div>
      </div>
    </div>
  </section>

According to https://getbootstrap.com/docs/4.0/layout/grid/ the grid should have 12 columns, so the col-lg-5 would occupy 5 of them, so that only two entries fits in a row. The third and forth entry would wrap in the next row. But actually we get a view with 3 entries in the first row, and one centered in the second row. Is the default bootstrap variable $grid-columns: 12; redefined? Or is this just some Hyas thing not related to Bootstrap? Of course, I can get it working somehow by try and error, but would be better to understand what is really going on.

[h-enk]

I set up Doks to use 16 columns (instead of the default 12) — my personal preference (for Doks)

https://github.com/gethyas/doks-core/blob/main/assets/scss/common/_variables-overrides.scss#L27

Something to mention in the docs

[StefanSalewski]

One more question:

Add pages

Add new pages to your site by creating .md or .html files in content/docs/. Use sub-folders to organize your files and to create multiple path segments.

So I assume all the md files have to reside in the docs directory. That is OK, but then you should mention that this is a magic directory, other places would not work.

~/nimprogramming.com $ npm run create docs/aaa/bbb.md

results in

$ tree content/
content/
├── blog
│   ├── example
│   │   └── index.md
│   └── _index.md
├── docs
│   ├── aaa
│   │   └── bbb.md
│   ├── guides
│   │   ├── example.md
│   │   └── _index.md
│   ├── _index.md
│   ├── reference
│   │   ├── example.md
│   │   └── _index.md
│   └── resources.md
├── _index.md
└── privacy.md

So the existing example entries all have _index.md files, but for my newly created aaa/bbb.md there is no _index.md. That is confusing. When they are not needed, why does the example have it. Or it is needed, and we have to create it our self manually?

[h-enk]

This is how Hugo works. Content lives in the content directory — see also the Hugo docs: Directory structure. Content is organized in "page bundles" — see also the Hugo docs: Content organization

So for example:

• content/docs/start-here/_index.md => https://getdoks.org/docs/start-here/
• content/docs/start-here/getting-started/index.md => https://getdoks.org/docs/start-here/getting-started/

Using page bundles also caters for using page resources (helping you keep things together) — see Page resource

[StefanSalewski]

I just found a strange issue of

$ npm run dev

That command can cache content and refuse to update, even when restarted. I had created a books directory inside of docs, and then renamed it to oldbooks, and created a new books directory. That fully confused the server. Finally I discovered that it had created a public directory, and served all the time that content. It noticed that I modified files, but still served the old content. Finally I deleted public, now all is OK again.

[h-enk]

Yes, sometimes you need to do that (and/or clear your browser cache — CTRL+ Shift+ Delete)

[StefanSalewski]

This is how Hugo works.

Thanks for the provided links, I will study them. But still I find it is inconsistent: The provided examples have files like content/docs/guides/_index.md, but when we create a new directory with command npm run create docs/aaa/bbb.md no _index.md file is created.

[h-enk]

Yes, you'd need to do that in a separate command: npm run create docs/aaa/_index.md

[StefanSalewski]

The server launched with "npm run dev" has a really strange behaviour!

$ tree content/docs/books
content/docs/books
└── books.md

created with "npm run create docs/books/books.md" gives a file not found message. But when I set the field draft to true, then the page is found. Note that for this case no _index.md file is involved. But when I set draft to false again, the page is still found. This makes experimenting a bit hard.

[h-enk]

Caching? What if you run the garbage collection: npm run dev -- --gc

[StefanSalewski]

No, that makes no difference. When I set for a content page draft to false, then that page remains visible, even when I set it back to true. Until I delete the whole public folder. But that is not a real problem, was just confusing to me first.

A last question for today: Currently my new books.md page is displayed well, but on the bottom there are these prev next links. I would like to disable them.

And one more: The command "npm run create docs/books/books.md" sets draft to true. But I always want it to be false. Do I always have to do this manually in my editor?

[h-enk]

Currently my new books.md page is displayed well, but on the bottom there are these prev next links. I would like to disable them.

Interesting one (this is not an option on a page to page basis). You could though override the default template and not show the links for all pages (it would be fairly easy to make this an option — note to self). Copy node_modules/@hyas/doks-core/layouts/_default/single.html and paste as /layouts/_default/single.html. Then, comment out line 51:

{{/* partial "main/docs-navigation.html" .  */}}

The command "npm run create docs/books/books.md" sets draft to true. But I always want it to be false.

Copy node_modules/@hyas/doks-core/archetypes/docs.md (this is the template for generating new docs pages) and paste it as /archetypes/docs.md (so, you're overriding it). Next, in the frontmatter set draft: false

[StefanSalewski]

Thank you very much for your advice. I think I will do that. The prev/next links at the bottom might be useful for some kind of documentation, e.g. for chapters of a book. But when the pages contain very different stuff, like a FAQ, a list of books, and an imprint, that info is not strongly related, so links makes not much sense.

[StefanSalewski]

I noticed that you have already updated and largely extended the documentation.

What might be still missing is how to add blog pages.

npm run create blog/testblog1/index.md

as used in v0.5 seems to work still, but some more explanations would be great.

[h-enk]

I'm working on it (pushing live what's available and better than nothing/before).

[StefanSalewski]

I am going to deploy the site now :-)

Currently I am unsure about the statement in the old documentation:

6. Deploy Your Site

Deploy your Doks site to Netlify or any other static web host.
👉
Make sure to set baseURL in ./config/production/config.toml to the URL of your Doks website in production.

The value for 1.x is

cat config/production/hugo.toml

Overrides for production environment

baseurl = "/"

Is that now OK, or have I to modify it as in v0.5?

Note that I can not use the detailed deploy instructions, but have to use the original Hugo way from https://gohugo.io/hosting-and-deployment/deployment-with-rsync/ for my all-inkl.com webhoster.

[StefanSalewski]

And it is done:

https://nimprogramming.com/

I have used the original deploy script created one year ago following https://gohugo.io/hosting-and-deployment/deployment-with-rsync/

So baseurl = "/" seems to be fine now.

So the whole update process took me only eight hours, which is less than expected. In the next few days I will do some fine-tuning, and then do the same for https://nimprogrammingbook.com/

[h-enk]

Congrats — looking good! You could/should preferably¹ set baseurl in

• config/_default/hugo.toml to http://localhost/
• config/production/hugo.toml to https://nimprogramming.com/

Footnotes

1. So you don't have relative, but absolute URL's in production (SEO thing) — see also https://nimprogramming.com/sitemap.xml ↩