I think we talked past each other. Let me try again.
So what you are saying is that I should actually commit only the math-quiz.scrbl file to GitHub? I suppose that also means that before doing that, I have to delete all the other files in scribblings folder on GitHub repo.
Yes and yes.
(Slightly off-topic: you might find the command
raco pkg new helpful for your new projects in the future, since it will generate a
.gitignore file that prevents you from checking in some of the compiled files)
Okay, I’ll try that, but still there’s this question; why do only these 3 secref links fail, when all the other links (section, subsection) work correctly?
I assume that you generate the HTML by using the “Scribble HTML” button in DrRacket. Is that correct?
The thing is, currently the generated HTML file with this method will use the absolute filesystem path on your system when resolving some links. That is why these 3 secref links failed. These HTMLs only work on your computer, and are not always appropriate for distribution to other systems.
Instead, you can simply distribute the Scribble source file. When people install your package (by using the package manager or the
raco pkg install command), the Scribble file will be locally compiled to HTML on the user’s system automatically. When the user clicks "View documentation" or runs
raco docs, they will get correct HTML with correct links on their system.
And again, you will find that https://docs.racket-lang.org/math-quiz/index.html is already correct. The 3 secref links work when the Scribble file is rendered as a part of package setup.
I do think, though, that it would be nice to improve Scribble. What you want is totally reasonable, and Scribble should be able to support that. In particular, @shhyou might have more thoughts on generating relative links. It is actually already possible for Scribble to generate relative paths, but the condition for that is pretty limited. IIUC, he experimented with relaxing the condition in https://github.com/racket/scribble/pull/315.