# Hyperlinks inside a scribble single file **URL:** \ **Category:** Questions & Answers\ **Created:** [November 20, 2023, 6:08am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519 "2023-11-20T06:08:30Z")\ **Posts on this page:** 17\ **Page:** 1
**Author:** ![hrvoje064](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hrvoje064/32/729_2.png) [@hrvoje064](https://racket.discourse.group/u/hrvoje064)\ **Post date:** [November 20, 2023, 6:08am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/1 "2023-11-20T06:08:30Z")
I have a problem with my scribble docs for math-quiz. It is a very simple (single) file (my first attempt at this), and contains just a few sections and subsections. Nothing fancy. This all works, except after I introduced several hyperlinks from inside one section to another section inside the same file. For some reason I can't figure out, these links are hard-coded to my local math-quiz path, and when installed as a Racket package on another computer, these links don't work. For example: ```scheme @section[#:tag "gapesa"]{GAPESA Exercises} ... section text... From another section ... @(secref "gapesa")... ``` This works only on my working copy of math-quiz package, but when installed on another computer, or as another user, it still uses the same path as on my local package. Any way to fix this? ---
**Author:** ![joeld](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/joeld/32/38_2.png) [@joeld](https://racket.discourse.group/u/joeld)\ **Post date:** [November 20, 2023, 8:03pm UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/2 "2023-11-20T20:03:37Z")
How are they installing the package? Is the documentation actually being rebuilt as part of that process? ---
**Author:** ![soegaard](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/soegaard/32/19_2.png) [@soegaard](https://racket.discourse.group/u/soegaard)\ **Post date:** [November 20, 2023, 8:15pm UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/3 "2023-11-20T20:15:16Z")
@joeld See [GitHub - hrvoje064/math-quiz-jasna: math-quiz for grade 1,2,3, ... elementary school. Written in Racket](https://github.com/hrvoje064/math-quiz-jasna) @hrvoje064 I can't spot anything unusual in the info file. Are you using DrRacket to make the executable? ---
**Author:** ![joeld](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/joeld/32/38_2.png) [@joeld](https://racket.discourse.group/u/joeld)\ **Post date:** [November 20, 2023, 9:54pm UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/4 "2023-11-20T21:54:38Z")
> [@soegaard](#): > > @joeld > See [GitHub - hrvoje064/math-quiz-jasna: math-quiz for grade 1,2,3, ... elementary school. Written in Racket](https://github.com/hrvoje064/math-quiz-jasna) I notice that rendered HTML files are included in the `scribblings` directory of the repo, and these files include the problematic machine-specific `file://` paths. (It would be better to exclude all `.css` `.js` and `.html` files in that folder from version control.) So the hunch which prompted my initial question is probably correct: whatever process is being used to copy these files and “install” them on the other computers is not rebuilding the docs locally the way a normal `raco pkg install` would. ---
**Author:** ![hrvoje064](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hrvoje064/32/729_2.png) [@hrvoje064](https://racket.discourse.group/u/hrvoje064)\ **Post date:** [November 21, 2023, 2:25am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/5 "2023-11-21T02:25:59Z")
No, I was doing that (using DrRacket to make the executable) before I installed math-quiz as a package on Racket package server. Now, I'm just updating my local source files, and pushing them to GitHub. And as far as I can see (when I update the math-quiz program on my daughter's windows computer), the package being updated from Racket server is being rebuilt locally. That is everything but these 3 hyperlinks I mentioned in original post. I have one menu entry in math-quiz program to update the program (using the DrRacket Package Management window), so I can follow what goes on during updating. What I find very confusing is that apart from these 3 links in scribble file (that are not updated), all the others are updated correctly. I mean, every section, and subsection declaration is a link, and I can check them just hovering the mouse over the section name on the gray area on the left, and it shows correct runtime path, all except these 3 `secref` links. ---
**Author:** ![sorawee](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@sorawee](https://racket.discourse.group/u/sorawee)\ **Post date:** [November 21, 2023, 2:59am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/6 "2023-11-21T02:59:29Z")
A couple of things: 1. Usually, a Racket package should not distribute HTML files with the repository. You should remove every file under [https://github.com/hrvoje064/math-quiz-jasna/tree/main/scribblings](https://github.com/hrvoje064/math-quiz-jasna/tree/main/scribblings) except `math-quiz.scrbl`. 2. When you install a package, Racket will automatically render Scribble source to HTML for you. Where it stores these HTML files could vary depending on how Racket is installed. For example, mine is stored at `/Users/sorawee/projects/racket/racket/doc/math-quiz/index.html` (although the locally cloned package is at `/Users/sorawee/projects/math-quiz-jasna/`). To view the documentation, use the command `raco docs`. The links in the rendered HTML are all correct. [https://docs.racket-lang.org/math-quiz/index.html](https://docs.racket-lang.org/math-quiz/index.html) is also rendered just fine. 3. `(define scribblings '(("scribblings/math-quiz.scrbl") ()))` in `info.rkt` is malformed. You should change it to `(define scribblings '(("scribblings/math-quiz.scrbl" ())))`. ---
**Author:** ![LiberalArtist](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/liberalartist/32/151_2.png) [@LiberalArtist](https://racket.discourse.group/u/LiberalArtist)\ **Post date:** [November 21, 2023, 3:41am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/7 "2023-11-21T03:41:11Z")
> [@sorawee](#): > > `(define scribblings '(("scribblings/math-quiz.scrbl") ()))` in `info.rkt` is malformed. You should change it to `(define scribblings '(("scribblings/math-quiz.scrbl" ())))`. It would be good to find the code that reads the `scribblings` key (I’d guess in the `racket-index` package) and have it report an error during `raco setup`. ---
**Author:** ![hrvoje064](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hrvoje064/32/729_2.png) [@hrvoje064](https://racket.discourse.group/u/hrvoje064)\ **Post date:** [November 21, 2023, 3:47am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/8 "2023-11-21T03:47:50Z")
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. 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? ---
**Author:** ![hrvoje064](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hrvoje064/32/729_2.png) [@hrvoje064](https://racket.discourse.group/u/hrvoje064)\ **Post date:** [November 21, 2023, 4:26am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/9 "2023-11-21T04:26:12Z")
Thanks. (for all 3 🤣). I guess I left all those files there, because I did not know how the package installation really works. Another reason was that if these files are not there (at least HTML) than downloading the source zip file from GitHub directly, without installing it as a racket package, will not work. That is, running the main.rkt file directly from DrRacket will work, but the HTML docs will not work. Although, that's probably not a valid reason, because I still keep the text docs in the program, and these work no matter how the program is installed. ---
**Author:** ![sorawee](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@sorawee](https://racket.discourse.group/u/sorawee)\ **Post date:** [November 21, 2023, 5:17am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/10 "2023-11-21T05:17:59Z")
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](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](https://github.com/racket/scribble/pull/315). ---
**Author:** ![hrvoje064](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hrvoje064/32/729_2.png) [@hrvoje064](https://racket.discourse.group/u/hrvoje064)\ **Post date:** [November 21, 2023, 5:20am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/11 "2023-11-21T05:20:11Z")
@LiberalArtist and have it report an error during `raco setup`. Actually, `raco setup` does report this error, I just wasn't looking at it. Too many lines to follow carefully. ---
**Author:** ![hrvoje064](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hrvoje064/32/729_2.png) [@hrvoje064](https://racket.discourse.group/u/hrvoje064)\ **Post date:** [November 21, 2023, 5:43am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/12 "2023-11-21T05:43:08Z")
@sorawee > (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) Thanks. I did try `raco pkg new`, but decided not to use it for math-quiz, as math-quiz is a long running program, so I was afraid it would mess up my existing files. Anyway I did notice that `.gitignore` file. Unfortunately, at that time I didn't even know what that is! ---
**Author:** ![hrvoje064](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hrvoje064/32/729_2.png) [@hrvoje064](https://racket.discourse.group/u/hrvoje064)\ **Post date:** [November 23, 2023, 1:07pm UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/13 "2023-11-23T13:07:07Z")
@sorawee > 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... Yes, and I now really have a valid reason for this. You might remember, that when I started this program I was originally posting it as a binary only package on [Jasna's Math Quiz by hrvoje064](https://hrvoje064.itch.io/jasnas-math-quiz) . Now, after following your advice, and that source package on [pkgs.racket-lang.org](http://pkgs.racket-lang.org) works, I tried to fix the binary only distribution as well. Unfortunately this does not work. If I follow the same recipe (keeping only math-quiz.scrbl in scribbling directory), I get nothing. So, to get something at least, I must populate (before compiling for distribution) scribblings directory with all the other files, including the math-quiz.html. Then everything works, but for these 3 local `secref` links, which are hardwired to my home directory. Actually, I did find the way to fix it (although I knew even before I started that this is useless). I used `(system (format "scribble ~a" path-to-math-quiz.scrbl))` that is to run first time user starts the program. This actually works (although all the files, including math-quiz.html end up in `bin` folder and not where scrbl file is). But of course this works only if user has Racket installed, and that defeats the purpose of binary distribution. ---
**Author:** ![soegaard](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/soegaard/32/19_2.png) [@soegaard](https://racket.discourse.group/u/soegaard)\ **Post date:** [November 23, 2023, 2:16pm UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/14 "2023-11-23T14:16:54Z")
A temporary fix would be to generate the html-files as you did originally, and the post-process the results with a small search/replace script to fix the offending urls. Far from an elegant solution, but one that works until a better solution shows up. ---
**Author:** ![hrvoje064](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hrvoje064/32/729_2.png) [@hrvoje064](https://racket.discourse.group/u/hrvoje064)\ **Post date:** [November 23, 2023, 2:25pm UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/15 "2023-11-23T14:25:38Z")
@soegaard OK, I'll try that. Thanks. ---
**Author:** ![sorawee](https://avatars.discourse-cdn.com/v4/letter/s/ea5d25/32.png) [@sorawee](https://racket.discourse.group/u/sorawee)\ **Post date:** [November 25, 2023, 2:04am UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/16 "2023-11-25T02:04:00Z")
I was under the impression that you want people to use your package via the package server. I see now that you want them to download the file from your website directly. FWIW, if you run the Scribble command with the `--dest` argument, relative links will be mostly used in the generated HTML under the specified directory. But you also want to provide `--redirect-main http://docs.racket-lang.org/` so that cross-ref links to stuff like `require` are not local to your computer. Something like: ```scheme scribble +m --dest html --redirect-main http://docs.racket-lang.org/ scribblings/math-quiz.scrbl ``` (Also thanks to Alexis whose new package made me realize the importance of --dest.) ---
**Author:** ![hrvoje064](https://yyz2.discourse-cdn.com/free1/user_avatar/racket.discourse.group/hrvoje064/32/729_2.png) [@hrvoje064](https://racket.discourse.group/u/hrvoje064)\ **Post date:** [November 25, 2023, 4:26pm UTC](https://racket.discourse.group/t/hyperlinks-inside-a-scribble-single-file/2519/17 "2023-11-25T16:26:43Z")
Yes, you were under the right impression, the preferred use now is via the package server. This is not only simpler but allows for menu click package update, which binary distribution does not allow. However, since I started this with binary distribution only, and that site is still alive, I wanted to fix that one as well. And thanks to @soegaard advice, it now is. Really, it was much simpler than I imagined it would be. I just have to make sure that my home path does not change 🤣