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 .md extension.

Start with a simple README.md:

# 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 .html extension. 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.

The root 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 README.md in it. Those README.md files can be blank.

Lines with no special treatment get converted into standard HTML paragraph tags.

Creating headers

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:

Screenshot of header styles H1 through H6

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 parentheses, ./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 other web pages 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 complete illustration.

Take the following file named contact.md:

# 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 README.md:

# 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 #rosie-greer:

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.