We'll improve search results by breaking down the manuals into smaller pages so they are more likely to get fully indexed by search engines, and by adding more relevant metadata.

The first step is probably not super hard to do, just needs some concentration. It has something to do with theinto-file directive: https://github.com/search?q=repo%3ANixOS%2Fnixpkgs%20into-file&type=code

We'll improve search results by breaking down the manuals into smaller pages so they are more likely to get fully indexed by search engines, and by adding more relevant metadata.

The first step is probably not super hard to do with a Python background, just needs some concentration. It has something to do with theinto-file directive: https://github.com/search?q=repo%3ANixOS%2Fnixpkgs%20into-file&type=code

It might be personal thing... I don't like those achor tags in our nix code because strictly bind our lib documentation to the current manual rendering, with those exact achor tags. Changing something in rendering (e.g. splitting in multiple pages) now means also breaking the documentation.

See [`lib.lists.foldl'`](#function-library-lib.lists.foldl-prime) but for attribute sets.

Has this been discussed in the documentation team? I'd prefer to keep the actual content un-opinionated from our rendering framework, and place neutral references, that are autoresolved instead of hard links, which break when touching the thing.

I don't like those achor tags in our nix code because strictly bind our lib documentation to the current manual rendering, with those exact achor tags. Changing something in rendering (e.g. splitting in multiple pages) now means also breaking the documentation.

See [`lib.lists.foldl'`](#function-library-lib.lists.foldl-prime) but for attribute sets.

Has this been discussed in the documentation team? I'd prefer to keep the actual content un-opinionated from our rendering framework, and place neutral references, that are autoresolved instead of hard links, which break when touching the thing.

I don't like those achor tags in our nix code because strictly bind our lib documentation to the current manual rendering, with those exact achor tags. Changing something in rendering (e.g. splitting in multiple pages) now means also breaking the documentation.

See [`lib.lists.foldl'`](#function-library-lib.lists.foldl-prime) but for attribute sets.

Has this been discussed in the documentation team? I'd prefer to keep the actual content un-opinionated from our rendering framework, and place neutral references, that are autoresolved instead of hard links, which break when touching the thing.
Is there some (un)/official guide for placing references?

In reply to @infinisil:matrix.org
I generally inspect the web elements to find them

And now we depend on a certain web-elements beeing present on the same page ^^.
I'll try to find a solution for this., because it hinders us moving to newer formats. Any suggestions?

idea:

Something like
see [lib.lists.foldl]

Without any further. The rendering framework can transform this into references for achor tags, if it uses them.
I tried using a different rendering framework that uses seperate pages and doesnt have those exact anchors.

In reply to @infinisil:matrix.org
I generally inspect the web elements to find them

And now we depend on a certain web-elements beeing present on the same page ^^.
I'll try to find a solution for this., because it hinders us moving to newer formats. Any suggestions?

idea:

Something like
see [lib.lists.foldl']

Without any further. The rendering framework can transform this into references for achor tags, if it uses them.
I tried using a different rendering framework that uses seperate pages and doesnt have those exact anchors.

That opens the box of pandora: context aware references ^^

{
   /**
   # Params

  - [a] A number
  - [b] Another number

   */
   lib.foo = a: b: a +b;
}

😃

That opens the box of pandora: context aware references ^^

{
   /**
   See also [lib.trivial.add]
   # Params

  - [a] A number
  - [b] Another number

   */
   lib.foo = a: b: a +b;
}

😃

Can't run nix.dev devmode:

❯ nix-shell --run devmode
error:
       … while calling the 'import' builtin

         at «string»:1:2:

            1| (import <nixpkgs> {}).bashInteractive
             |  ^

       … while calling the 'findFile' builtin

         at «string»:1:9:

            1| (import <nixpkgs> {}).bashInteractive
             |         ^

       error: file 'nixpkgs' was not found in the Nix search path (add it using $NIX_PATH or -I)

       at «none»:0: (source not available)
will use bash from your environment
Doing an initial build of the docs...

In reply to @johannes.kirschbauer:scs.ems.host
Whats in your $NIX_PATH, is it empty ?

In reply to @asymmetric:matrix.dapp.org.uk

Can't run nix.dev devmode:

❯ nix-shell --run devmode
error:
       … while calling the 'import' builtin

         at «string»:1:2:

            1| (import <nixpkgs> {}).bashInteractive
             |  ^

       … while calling the 'findFile' builtin

         at «string»:1:9:

            1| (import <nixpkgs> {}).bashInteractive
             |         ^

       error: file 'nixpkgs' was not found in the Nix search path (add it using $NIX_PATH or -I)

       at «none»:0: (source not available)
will use bash from your environment
Doing an initial build of the docs...

In reply to @johannes.kirschbauer:scs.ems.host

It might be personal thing... I don't like those achor tags in our nix code because strictly bind our lib documentation to the current manual rendering, with those exact achor tags. Changing something in rendering (e.g. splitting in multiple pages) now means also breaking the documentation.

See [`lib.lists.foldl'`](#function-library-lib.lists.foldl-prime) but for attribute sets.

Has this been discussed in the documentation team? I'd prefer to keep the actual content un-opinionated from our rendering framework, and place neutral references, that are autoresolved instead of hard links, which break when touching the thing.

We haven’t discussed this, but someone recently made me aware of https://github.com/stepchowfun/tagref

I think it’s a nice idea, and seems like it would scale better than the reference system Sphinx uses (which in its MyST incarnation can’t discern between file paths and references… it produces a lot of busywork).

In reply to @alejandrosame:matrix.org
I think my new PR fixes this completely. At least it does handle properly the syntax error you mention in your issue :)