Confused about relref when writing documents

[wolfogre]

I’m confused about how to use relref when writing documents, I'm sorry if I missed any guidance. But I want to clarify my confusions before I figure them out, this will help to understand a new contributor's confusion.

Let's say I'm a guy who:

• know how to use hugo basically.
• will copy existing examples if I don't know how to do it.
• try to add/update docs for Gitea.

Some mistakes I made because of this:

• Fix broken links in documents #24630
• Unable to build documentation - [zh-tw] REF_NOT_FOUND #24511 (comment)

And there are my confusions about relref:

I see two ways to link a page

I see both HTML style:

gitea/docs/content/doc/development/hacking-on-gitea.en-us.md

Line 269 in bb25f85

<a href='{{< relref "doc/administration/config-cheat-sheet.en-us.md" >}}'>configuration cheat sheet</a>

and markdown style:

gitea/docs/content/doc/development/hacking-on-gitea.en-us.md

Line 182 in bb25f85

Frontend development should follow [Guidelines for Frontend Development]({{< relref "doc/contributing/guidelines-frontend.en-us.md" >}})

However, the first one doesn't seem to be working.

When I'm writing x.zh-cn.md, I cannot link y.en-us.md

The error message will be REF_NOT_FOUND, like:

ERROR 2023/05/10 10:38:15 [zh-cn] REF_NOT_FOUND: Ref "doc/administration/config-cheat-sheet.en-us.md": "x/gitea/docs/content/doc/development/hacking-on-gitea.zh-cn.md:255:6": page not found

I was confused because the file does exist. After a few attempts, I understand now, I should use y.zh-cn.md instead, even if it doesn’t exist. And make docs will copy y.en-us.md to y.zh-cn.md, then it will work.

So the rule could be: when writing x.zh-cn.md, link to files with the suffix .zh-cn.md only, whether they exist or not. To be honest, I'm not sure if the rule is correct.

BTW, I think Hugo can do this better (I understand that there may be historical legacies that prevent us from doing so easily):

• Multilingual Mode
• Link to another language version

How to preview when writing

When I'm writing a document, I run cd docs && make server to preview the page. However, sometimes it fails with many REF_NOT_FOUND errors due to the reason mentioned earlier.

I know what to do: make docs && cd docs && make server. It works! I can go on writing happily. And when I'm done, OMG, I see hundreds of new files and get crazy trying to commit the files I wrote only carefully.

[lunny]

relref has gone after converting from hugo to docusaurus, so let's close this issue.