Description
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:
and markdown style:
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):
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.
