file paths

a key concept in web design is the file path. a file path is simply a string that describes the location of a file in a filesystem. each directory (or "folder") that you have to open before you can reach the file is separated from the filename by a forward slash. so if you have a file data saved in the folder b, which itself is in the folder a, you would refer to it by the path a/b/data.

when you reference one file from another (such as by linking to it), it's important to note that the URL must be that of the compiled address of a file. while the file you are currently reading is named markdown.md behind the scenes, pub.pl generates an HTML file from it, with the name markdown.html. for more information on how filenames (and files) are transformed, see input files.

you can create both relative and absolute links. relative links are from the perspective of the directory that the current file is located it. so if you're editing a file in the same directory as the file you're linking to, you can simply write the name of the file. however, if it's in another directory, you might want to use an absolute path: any URL that begins with a / points to something in the root src directory. so the file index.md in the docs directory could be reached from here by the URL index.html or the URL /docs/index.html (/index.html being a different file entirely).

if you need to link to something that's one directory up but don't want to use an absolute URL, you can instead use the ../ notation. .. is a special directory link that points back up to parent of the current directory. since this file is located in the /docs directory, we could link from it to index.md as either /index.html or ../index.html. in general, you should only do this if both this file and the other one are in a directory whose path is liable to be changed. as an example, all links between documentation files are relative, so the doc folder can be moved or renamed without breaking them.

to link to a page on a completely different site, just copy the whole URL from your address bar (including the http:// or https:// part) and put it between the parentheses. for instance, this link to google is written \[google](https://google.com).

to give you a better sense of path syntax, here's a list of every file and directory in the default distribution with its full path. you can open up a file browser to see how this works, or open a terminal, cd to the project directory and run the tree command to see a visual print-out of the whole directory structure.

• /pub.pl
• /up.sh
• /cfg
• /cfg/links
• /cfg/sitename
• /src
• /src/index.md
• /src/style.css
• /src/header.png
• /src/doc
• /src/doc/index.md
• /src/doc/input-files.md
• /src/doc/markdown.md
• /src/doc/using-pub.md