Minor issue for highlighting the active topic links

[StefanSalewski]

It is a bit difficult to explain this tiny issue. At least I think it is an issue, as I have no idea what I might have done wrong.

My two pages

https://nimprogramming.com/ and https://nimprogrammingbook.com/ have no been updated to latest Hyas/Doks, and are mostly fine.

One observation is, that the highlight of selected links does sometimes not work. For example, for https://nimprogramming.com/ we have at the top the menu bar with "Nim About-Nim Tutorials ...". When I click on "Tutorials" that link is drawn blue and bold. But when I click on "About-Nim" there is no blue and bold, just plain display. The same for the other links in the menu, sometimes highlight works, sometimes not. The same for https://nimprogrammingbook.com/ -- for "Blog" highlight works, for "Imprint & Contact" not.

That is with Firefox on Linux.

Similar problems for right side links of https://nimprogramming.com/docs/about-nim/

For some links highlight works, for others not. And sometimes I click on one link, and another one is highlighted.

Here is the source-code of that page, should be OK:

$ cat ~/nimprogramming.com/content/docs/about-nim/about-nim.md 
---
title: "About Nim"
description: ""
summary: ""
date: 2024-05-13T23:38:20+02:00
lastmod: 2024-05-13T23:38:20+02:00
publishDate: 2023-10-19T00:40:04-07:00
draft: false
weight: 999
toc: true
seo:
  title: "About Nim" # custom title (optional)
  description: "" # custom description (recommended)
  canonical: "" # custom canonical URL (optional)
  noindex: false # false (default) or true
---
## The Nim Programming Language

### Introduction

Nim is a statically-typed, high-level programming language that
combines the performance of low-level languages like C and C++ with
the expressiveness of high-level languages like Python, Lisp, and
Haskell. Created by Andreas Rumpf in 2008, Nim was initially named
"Nimrod" before being renamed in 2014. Notable features include a
clean, Python-inspired syntax,
automatic memory management without the disadvantages of traditional GC's (ARC/ORC),
powerful compile-time metaprogramming through AST-based macros, cross-compilation
support, and built-in concurrency mechanisms.
The language is
suitable for systems programming, general-purpose programming, scripting,
game development, and scientific computing.

### Latest release

<!-- * Latest stable release: Version 1.6.12 (10 March 2023) -->
<!-- * Version 2.0.0 RC2 (release candidate, 31 March 2023) -->
Nim 2.0.4 has been released on 16 April 2024. See the official announcement at [Nim 2.0.4](https://nim-lang.org/blog/2024/04/16/versions-1620-204-released.html)

### Nim is often characterized by its Efficiency, Expressiveness, and Elegance.
* Nim generates native, dependency-free executables that do not rely on
a virtual machine, enabling compact size and effortless redistribution.
* The Nim compiler and its generated executables are compatible with all
major platforms, including Windows, Linux, BSD, and macOS.
* Nim's memory management, inspired by C++ and Rust, is deterministic and
customizable with destructors and move semantics, making it well-suited
for embedded, hard-realtime systems.
* Modern concepts such as zero-overhead iterators and compile-time
evaluation of user-defined functions, coupled with a preference for
value-based datatypes allocated on the stack, result in highly performant
code.
* Nim supports various backends, compiling to C, C++, or JavaScript, making
it an ideal choice for both backend and frontend needs.  An optional LLVM
backend is also available, enabling further performance enhancements on
supported systems and bypassing the need for intermediate C or C++ code.
* Nim is self-contained, as both the compiler and the standard library
are implemented in Nim itself.
* With a powerful macro system, Nim allows direct manipulation of the AST,
providing nearly limitless possibilities.
* Nim features a modern type system, complete with local type inference,
tuples, generics, and sum types.

### Features

Nim boasts several key features that make it an attractive language
for developers:
* Statically typed: Nim is a statically typed language, which means that
type checking is performed at compile time, reducing the likelihood of
runtime errors.
* High-level syntax: Nim's syntax is clean, concise, and expressive,
drawing inspiration from languages like Python and Haskell.
* Memory Management: Nim offers multiple automatic memory management
strategies. Traditional garbage collection (--mm:refc) can be optionally
substituted with a fully deterministic, destructor-based memory management
(--mm:arc, --mm:orc), which circumvents common GC issues such as
execution pauses ("stop the world") and increased executable size due
to the GC runtime system. ORC memory management operates effectively
even with cyclic data structures and serves as the default option for
Nim 2.0. Traditional GC remains available, and manual memory management
is also possible.
* Metaprogramming: Nim allows for powerful compile-time metaprogramming
through its macro system, enabling developers to write generic,
reusable code.
* Cross-compilation: Nim supports cross-compilation, making it possible
to compile code for different platforms and architectures.
* Performance: Nim compiles to C, C++, or JavaScript, resulting in
high-performance executables that rival the speed of native C and C++
applications. An optional LLVM backend can be used as well.
* Concurrency: Nim provides built-in support for parallel and concurrent
programming with its async/await and parallel statement features.
* Nim features a top-notch JavaScript backend, enabling seamless targeting
of both client-side and server-side applications simultaneously.
* Nim implements a small core language with a powerful set of metaprogramming features.

### Syntax

Nim's syntax is inspired by Python, making it easy to read and
write. Some notable syntax features include:
* Indentation-based scoping: Like Python, Nim uses indentation to define
blocks of code, eliminating the need for curly braces.
* Type inference: Nim can infer the type of a variable based on its value,
allowing for more concise code.
* First-class functions: Functions are first-class citizens in Nim,
allowing them to be assigned to variables, passed as arguments, or
returned as values from other functions.
* Multiple dispatch: Nim supports multiple dispatch, which means that
functions can be overloaded based on the number of arguments and their
types.
* An intriguing feature shared by Nim and D-lang is the method call
syntax, originally termed "Uniform Function Call Syntax" (UFCS) in the D
language. This feature merges the traditional imperative programming style
with the occasionally more convenient OOP syntax. Instead of len(myStr),
we can alternatively write mystr.len() or simply mystr.len. In this case,
the string parameter assumes the role of self parameters in OOP code,
and this notation also works with additional parameters. For example,
write(file, data) is equivalent to file.write(data). The Nim compiler
recognizes each notation and generates identical code, allowing for OOP
style without necessitating the use of actual classes. This works even
for fundamental data types like integer numbers, so abs(i), i.abs(),
or i.abs can all be utilized.
* Object-Oriented Programming (OOP):
Similar to other modern programming languages such as Go and Rust, Nim accommodates OOP program design,
featuring inheritance and runtime method dispatch. However, it does not impose this coding style on programmers.
* Global Namespaces: In Nim, modules are typically imported using
statements like "import strutils" rather than the qualified form "from
strutils import split, join, ...". This approach is convenient, as
it allows for the usage of split(myString) or myString.split without
the need to prefix the function name with the module name, as in
stringutils.split(myString). For those accustomed to untyped languages
like Python, this unqualified import may seem unusual. However, since
Nim is a statically and strongly typed language, function overloading
results in namespace conflicts only in very rare cases. These conflicts
are reported by the compiler and can be easily resolved by applying a
module name prefix when necessary. For constants or enumeration types,
name conflicts are more likely, so qualified names are typically employed
for these data types. Regrettably, qualified import conflicts with
the method call syntax: while strutils.split(myString) is possible,
myString(strutils.split) is not allowed.
* Case Sensitivity: Historically, Nim was a fully style-insensitive
language, which meant that it was not case-sensitive, underscores
were disregarded, and there was no differentiation between foo and
Foo. However, since version 1.0 in 2019, the first letters of symbols
are compared in a case-sensitive manner, while other letters are
compared case-insensitively within the ASCII range and underscores are
ignored. This unconventional approach to identifier comparisons, known as
"partial case-insensitivity," offers several advantages over traditional
case sensitivity: It permits programmers to predominantly use their preferred spelling
style, whether it be humpStyle or snake_style, and ensures that
libraries created by different programmers do not utilize incompatible
conventions. A Nim-aware editor or IDE can display the identifiers
according to the user's preference. Additionally, this approach liberates
the programmer from memorizing the precise spelling of an identifier. The
exception for the first letter enables common code like var foo: Foo to
be parsed unambiguously. It is worth noting that the
compiler option --styleCheck:off|hint|error can generate hints or errors
for Nim identifiers that do not conform to Nim's official style guide,
and --styleCheck:usages enforces consistent spellings of identifiers
without imposing the style on declarations.

### Metaprogramming

Nim's macro system offers powerful compile-time metaprogramming
capabilities. These macros function as code generators during the
compilation process, empowering developers to create more expressive
and versatile code. Nim's macro system is Turing-complete, signifying
its ability to express any computation that a Turing machine can
perform. Common applications of macros in Nim encompass code generation,
domain-specific languages, and optimization.

The metaprogramming features in Nim provide support for generics,
templates, and macros, allowing for the extension of Nim with various
programming paradigms and helping developers minimize boilerplate
code. The standard library incorporates async-await using these
metaprogramming features, and the Nim community has developed numerous
packages implementing diverse programming paradigms.

### Standard Library

Nim's standard library is extensive, providing modules for various tasks,
including:
* Data structures: Lists, sets, hash tables, and more
* File I/O: Reading, writing, and manipulating files and directories
* Networking: Sockets, HTTP, and other network protocols
* Concurrency: Threads, locks, and async I/O
* Mathematics: Basic math operations, random number generation, and more
* Cryptography: Hashing, encryption, and more
* JSON and XML: Parsing and generating JSON and XML data
* Regular expressions: Pattern matching and manipulation
* Dates and times: Timezone-aware date and time operations

### Community and Ecosystem

Nim has an active community with many resources available
for learning and using the language:
* Official website: [Nim](https://nim-lang.org/) - Provides documentation,
downloads, and other resources for Nim developers.
* GitHub repository: [GitHub](https://github.com/nim-lang/Nim) - The official
source code repository for the Nim compiler and standard library.
* Nimble package manager: Nimble is the official package manager for Nim,
making it easy to install and manage third-party libraries.
* Forums: The Nim Community [Forum](https://forum.nim-lang.org/)
provides a platform for users to discuss the language, share projects,
and ask questions.
* Discord and IRC channels: Real-time chat channels for Nim users to
collaborate and seek assistance.
* Books and tutorials: Several books and online tutorials are available
for learning Nim, catering to various skill levels and interests.
* Conferences and meetups: annual conferences, such as NimConf, and local
meetups help bring the community together and promote the exchange of
ideas and experiences.

### Notable Projects and Applications
<!-- your comment text -->

Nim has been used to create various applications, libraries, and
frameworks, demonstrating its versatility and power. Some notable
examples include:
* [Nim Skull](https://github.com/nim-works/nimskull): A Nim-based programming language
* [NLVM](https://github.com/arnetheduck/nlvm): LLVM-based compiler backend
* [Regex](https://github.com/nitely/nim-regex): Pure Nim regex engine
* [NPeg](https://github.com/zevv/npeg): Pure Nim PEG's implementation
* [Pixie](https://github.com/treeform/pixie): Pure Nim full-featured 2d graphics library
* [Futhark](https://github.com/PMunch/futhark): Automatic wrapping of C headers
* [Moe](https://github.com/fox0430/moe): A command-line-based editor inspired by Vim.
* [Chronos](https://github.com/status-im/nim-chronos): Efficient asynchronous programming
* [NimForUE](https://github.com/jmgomez/NimForUE): Plugin for UE5 with native performance
* [Nitter](https://github.com/zedeus/nitter). An alternative Twitter front-end
* [Atlas](https://github.com/nim-lang/atlas): Package cloner
* [Malebolgia](https://github.com/Araq/malebolgia): Simplifies the implementation of concurrent and parallel programming
* [HappyX](https://github.com/HapticX/happyx): Macro-oriented asynchronous full-stack web-framework
<!-- * [Taskpools](https://github.com/status-im/nim-taskpools): lightweight threadpool -->
<!-- * [Weave](https://github.com/mratsim/weave): state-of-the-art multithreading -->
<!-- * [Karax](https://github.com/karaxnim/karax): Single-page web app -->

### Comparison to Other Languages

Nim can be compared to other programming languages in terms of its syntax,
performance, and features:
* Syntax: Nim's syntax is similar to Python, making it easy to learn
for Python developers. However, it also incorporates elements from other
languages like Lisp, Haskell, ADA, and the Wirthian language family (Pascal/Modula/Oberon).
* Performance: Due to its compiled nature, Nim's performance is comparable
to languages like C and C++. However, its high-level syntax and features
make it more expressive and easier to use than those languages.
* Features: Nim offers a unique blend of features, such as metaprogramming
and cross-compilation, that set it apart from other languages. Its focus
on performance and expressiveness makes it suitable for a wide range of
applications, from systems programming to web development.

### Conclusion

Nim is a powerful and versatile programming language that combines the
performance of low-level languages with the expressiveness of high-level
languages. Its clean syntax, extensive standard library, and powerful
metaprogramming capabilities make it an attractive choice for developers
seeking a modern, efficient language for their projects. With a growing
community and ecosystem, Nim is poised to make a significant impact on
the programming landscape.

Paste the information here as shown by npm run info

salewski@hx90 ~/nimprogramming.com $ npm run
Scripts available in [email protected] via `npm run-script`:
  create
    hugo new
  dev
    hugo server --disableFastRender --noHTTPCache
  format
    prettier **/** -w -c
  build
    hugo --minify --gc
  preview
    vite preview --outDir public

salewski@hx90 ~/nimprogramming.com $ npm run info
npm error Missing script: "info"
npm error
npm error To see a list of scripts, run:
npm error   npm run

npm error A complete log of this run can be found in: /home/salewski/.npm/_logs/2024-05-17T09_27_36_284Z-debug-0.log

Two other remarks: A feature to hide the links at the bottom of content pages world be fine. You told me already a way to remove them, but I have let then visible for now.

I like the dark mode for my pages. Is it possible to make dark theme the default, or have each user select dark on its own? Some users might not know that they can switch to the dark theme.

[StefanSalewski]

This issue occurs also when I run the locale server with

npm run dev

Your provided example page do not show such issues, but that page has not much content. From the links at the top of the page, we might get the feeling that names with spaces or hyphens has this issue. But comparing with the similar issue of the link section on the right, some links with space work, and some not. So no idea from my side.

[StefanSalewski]

Links at the right of your page https://getdoks.org/docs/reference/markdown-extended-syntax/ has issue too:

First entry "Table" gets highlighted.

Second entry "Fenced code block" gets not highlighted when clicked, but third entry instead!

For all following links, there is an offset of one.

Similar issues for the right menu in https://getdoks.org/docs/reference/markdown-basic-syntax/

[h-enk]

I like the dark mode for my pages. Is it possible to make dark theme the default, or have each user select dark on its own? Some users might not know that they can switch to the dark theme.

There are some options for that in config/_default/params.toml (line15..16):

# Doks (@hyas/doks-core)
[doks]
  # Color mode
  colorMode = "dark" # auto (default), light or dark
  colorModeToggler = false # true (default) or false (this setting is only relevant when colorMode = auto)

[StefanSalewski]

So setting the initial default to dark, and still showing the colorModeToggler, is not possible? What I would like best is having dark mode as default (when the page is visited for the first time) but giving the user the option to switch to light. Well, maybe that is technically not possible -- no problem, most users should be smart enough to discover the color toggler. Perhaps "auto" is indeed the best default.

The actual "issue for highlighting the active topic links" is still present. I have done some more testing, and have no idea what is actually going on, but it works not always correctly.

[h-enk]

So setting the initial default to dark, and still showing the colorModeToggler, is not possible?

That's correct. This is how it works currently:

• When colorMode is set to "auto", it respects the users' system-wide setting — so, it's light in the browser when it's set to light system-wide (for apps et cetera) and vice versa.
  • In addition, when you set colorModeToggler to true, the user can locally override (Doks website level) the system-wide settings.
• When colorMode is set to "dark", the Doks website always shows in dark mode, regardless of the user's system-wide setting.
• When colorMode is set to "light", the Doks website always shows in light mode, regardless of the user's system-wide setting.

We could extend the logic for your use case I think, but I'm not 100% sure yet — I have to give it some more thought (how would it work with the system-wide setting — which one wins so to speak).

[h-enk]

The links in the Table of Contents get highlighted using Scrollspy.

Settings are via data attributes in node_modules/@hyas/doks-core/layouts/_default/baseof.html (line 5):

<body class="{{ delimit (.Scratch.Get "class") " " }}"{{ if eq site.Params.doks.scrollSpy true }} data-bs-spy="scroll" data-bs-target="#toc" data-bs-root-margin="0px 0px -60%" data-bs-smooth-scroll="true" tabindex="0"{{ end }}>

If you'd like to customize data-bs-root-margin="0px 0px -60%", copy the file over to layouts/_default/baseof.html and make your changes there.

[h-enk]

I noticed that when you add and remove content, the active class on main navbar items do not always get updated.

What I find is that when I clean Hugo's build directories (and run the dev command again), it works like it should (for me).

So, try with running something like:

npx shx rm -rf public resources .hugo_build.lock

[StefanSalewski]

So, try with running something like:

npx shx rm -rf public resources .hugo_build.lock

When I run that, I get a warning:

salewski@hx90 ~/nimprogramming.bak $ npx shx rm -rf public resources .hugo_build.lock
Need to install the following packages:
[email protected]
Ok to proceed? (y) yes

npm warn deprecated [email protected]: This module is not supported, and leaks memory. Do not use it. Check out lru-cache if you want a good and tested way to coalesce async requests by a key value, which is much more comprehensive and powerful.
sh: /home/salewski/.npm/_npx/f3af5d8365aa3b70/node_modules/.bin/shx: /usr/bin/env: bad interpreter: Text file busy

But it might fix the issue, I will further investigate.

But note that your own page has a similar issue as well, as I wrote before:

#1241 (comment)

[StefanSalewski]

OK, no warning with a copy of my own page:

salewski@hx90 ~ $ cp -r nimprogramming.com /tmp/nimprogramming.com
salewski@hx90 ~ $ cd /tmp/nimprogramming.com
salewski@hx90 /tmp/nimprogramming.com $ npx shx rm -rf public resources .hugo_build.lock
salewski@hx90 /tmp/nimprogramming.com $ npm run dev

But still issues with the link menu on the right!

Well this is for firefox-126.0, I have currently no other browser available. If you can not reproduce this issue, I could test later with Chromium browser, but that one takes a few hours to build from source on my Gentoo box.

[h-enk]

But still issues with the link menu on the right!

Not sure if (and how) this can be fixed properly — it's a Bootstrap thing (to be taken upstream).

See also for example this Bootstrap documentation link (expected to highlight Methods, but highlighting Events instead — when clicking Methods in the ToC): https://getbootstrap.com/docs/5.3/components/scrollspy/#methods

[h-enk]

There are no ideal Options that fit all use cases (unfortunately), so you could tinker with them to support your setup (or accept the current situation — for now)

[StefanSalewski]

Well it is not a too important issue, only careful users might notice it. Your advice "npx shx rm -rf public resources .hugo_build.lock" seems to have fixed the link menu at the top, which is more important.

My sides look really good now, and work well. So I made a $20 donation to the Doks projects yesterday. Not much, but the two pages are nothing I get any profit from. I sold only two pieces of the Nim book in the last 12 months, so before updating the pages to Doks 1.x, I even considered fully removing them from Internet.

[h-enk]

Thanks for your financial contribution and for raising your questions and sharing your thoughts. It helps to improve Doks!

Are you ok with me adding the Nim Programming Book site to the Doks showcase? It will get you some traffic and hopefully more book sales 😉

[StefanSalewski]

Yes of course, you can use both pages as showcase. I think the general Nim info page created with help of GPT-4 is more interesting:

https://nimprogramming.com/

The book page https://nimprogrammingbook.com/ is more boring. And I have no hope to selling more Nim books -- while the Nim language is really a fine language, it seems to be in trouble now, many old users left, and no new users are coming. A good languages makes not that much sense, when the number of users and developers drops nearly to zero. I have to admit that I have done no Nim work in the last 12 months any more, mostly for personal differences with the core Nim dev. I am learning Rust now. Python, Go, Rust, Julia, Mojo, Kotlin seems to be the more attractive candidates for most people now.

[h-enk]

I added the Nim Programming site: https://getdoks.org/showcase/

Good luck and all the best!