Create and link to more pages
All VuePress sites have at least one directory containing a
README.md text file
formatted using Markdown. That directory may contain other Markdown files with the
Start with a simple
# Welcome to to Example.com We hope you love this tiny tiny site. Need to [contact someone](./contact.md) on the team?
Special properties of README.md
Markdown files get converted into HTML files by the same name, but with an
README.md is an exception. It gets renamed completely, to
index.html, because by convention that's
how web servers normally find the root file of a website.
README.md file must start with a header. It doesn't have to be an H1 (
# as shown above) but it should
be either H2 (
##) or H3 (
###) for proper generation of search indexes and sidebars.
Another property of
README.md as mentioned before is that if you want to organize
your site using subdirectories, a subdirectory is invisible to VuePress unless it has a
in it. Those
README.md files can be blank.
Lines with no special treatment get converted into standard HTML paragraph tags.
Lines starting with
# get converted to HTML H1 headers, lines starting with
## become H2 headers, and so on.
Organize your site carefully using headers because levels H1-H3 are indexed automatically by VuePress
for its blazingly fast search dialog.
Putting words most relevant to your audience into headers also helps in search engine results.
# Top level header, aka H1 H1 is the most important header. ## Second level header This gets converted to an H2 ### Third-level header VuePress indexes only up to H3 for its searches #### Level 4 header, aka H4 People remember only about 3 levels of a hierarchy ##### H5 Who goes this low? and why? ###### H6 A level 6 header is used only by spelunkers. Normal text isn't indexed by VuePress's internal search.
And the result is pretty much what you'd expect:
Markdown such as
[contact someone](./contact.md) gets turned into an HTML link. The part
of the link in square brackets,
contact someone in this case, becomes the anchor text (the
visible part of a link, and the part that gets indexed by search engines). The part in
./contact.md in this case, gets becomes a reference to an HTML file by the same
name, which would be
contact.html in the current directory.
Linking to external web sites using Markdown
The format for linking to other websites is similar to Markdown but you just use the website's actual URL in parentheses. For example:
Try [Google](https://www.google.com/) for more info.
Linking to headers inside a file
VuePress secretly turns every header into its own named file location.
This lets you navigate not just to a file, but to any header
in that file. You do it by following the filename with the header,
where spaces have been removed and punctuation is replaced with
spaces. For example,
contact.md#rosie-greer. Here's a
Take the following file named
# Contact Here's whom to call when you have a problem. ## Tyler Perry He has two first names! How cool is that? ## Rosie Greer When two heads are better than one.
Suppose you want to link right to Rosie, not just to the Contact page itself?
Let's try linking to Rosie's location inside
contact.md in a slightly modified
# Welcome to to Example.com ## This just in! Good news! [Rosie's](./contact.md#rosie-greer) head graft is a major success! Let's face it. You're darn lucky to be here. Need to [contact someone](./contact.md) on the team?
As you can see, the anchor to a header such as
## Rosie Greer flattened out.
Everything gets converted to lower case, and spaces are replaced with hypens.
This location name is synthesized as
Good news! [Rosie's](./contact.md#rosie-greer) head graft is a major success!
If you click Rosie's name you'll be taken directly to that position in the file.