How to add non scribble file to a scribble based website

Question

I can use image to embed an image in my scribble document, and the render function will copy it to the target destination. Now, I would also like to include files with my document that is not an image, such as an MP3 or PDF file that can be downloaded.

Additionally, I can't just include the file in the source folder and link to it, because if I render the document into a different target folder, it does not get copied.

Finally, I know I can just create the target directory by hand, and paste the file there. Or I can modify whatever file I'm using to build my document to copy the file. This is not satisfying though because now I have to track the image in two places. The .scrbl source file, and either the target directory or the build file.

So, is there a way in scribble that I can include a non scribble (or image) file such as an MP3 or PDF such that the render function knows to grab it and include it with the document?

score 4 · Accepted Answer · edited May 16 '18 at 17:16

Although it is a bit of a kludge, you can combine image with hyperlink to get your desired result. You use the image function to get the render function to copy the file, and hyperlink to add a link to it. Your document will look something like:

Here is a @image{file.mp3}@hyperlink["file.mp3"]{file}.

This works because the image function also expects a list of extensions to try to embed, but this list defaults to the empty list, and such it won't embed the file, but only copy it into the destination. You can then use hyperlink to link to the now copied file.mp3 file.

You can combine this into one operation with the following function:

(define (embed-file file . content)
  (list
    (image file)
    (apply hyperlink file content)))

And now you can use embed-file in your own document with:

Here is a @embed-file["file.mp3"]{file}.

(I should note that this idea came from Ben Lerner.)

score 2 · Answer 2 · edited Jun 20 '20 at 09:12

I took over somebody's code base and they had solved this issue using the solution above/below mine provided by Leif Andersen. However, this caused problems when linking to files that were part of subfolders in the source directory. The file in question was moved to the root of the output directory, while the hyperlink did not correctly update. Instead, I found the following less hack-y solution.

You can make use of the link-resource structure of the scribble/html-properties module. This expects the path of the original file. You place this link-resource into a style struct of the scribble/core module. Finally, this style is passed as an argument to hyperlink.

Putting it all together, the embed-file function instead becomes

(define (embed-file file . content)
  (apply hyperlink
         file
         content
         #:style (style "place-resources-in-output-folder" ; name
                        (list (link-resource file)))))

Where the "place-resources-in-output-folder" is just a name I give to the style.

This ensures the files are both moved to the root output folder and correctly linked.

How to add non scribble file to a scribble based website

2 Answers2