doc:page_section_headings [Knowledge Commons]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
//part of the [[start|GtC documentation]]//

====== Paragraphs and page section headings ======

When we talk about headings, we often use "h1" to mean a top-level heading, like a page title, because in HTML it is coded as `<h1>`. h2 is the next level down, etc.

The heading above – "Paragraphs and page section headings" – is a top-level, or h1 heading.
The heading  below – "Using the editing menu" – is an h2 heading.

Paragraph breaks are created simply by leaving a completely blank line between paragraphs. This is true for all the lightweight markup languages that we mention here.

Try out all these techniques below in the [[playground:playground]].

----

===== Using the editing menu =====

Headings are created using the H items in the menu.

  * `H=` gives you another heading at the same level you are currently at, or an h1, top level heading if you don't have a heading in your page already.
  * `H<` gives you a heading at a lower level than the previous one above
  * `H>` gives you a heading at a higher level than the previous one above
  * `H#` allows you to choose the heading level you want

----

===== DokuWiki syntax =====

  * For a top-level, h1 heading, on a separate line, put 6 `=` signs, `======` either side of your heading text.
  * For a next level, or section heading, similarly, put 5 `=` signs, `=====` either side of your heading text.
  * And so on. In DokuWiki, it is vital to balance the number of `=` signs equally on each side.
  * Don't put any blank space at the beginning or the end of the line, but you can put spaces between the `=` signs and the text.


==== This has 4 = signs, and is an h3 heading ====

=== This has 3 = signs and is an h4 heading ===

== This has 2 = signs and is an h5 heading ==

Note that you cannot format text or have links within DokuWiki headings.

===== Markdown syntax =====

Markdown syntax does work in our DokuWiki setup, with the help of a plugin.
To see more clearly how these are coded, you can try to Edit, then Cancel.

----
`# An h1 heading with one "#" sign`

# An h1 heading with one "#" sign

```
Another h1 heading, made by putting '='s underneath
==================================================
```

Another h1 heading, made by putting '='s underneath
==================================================

`## An h2 heading with two "##" sign`

## An h2 heading with two "##" sign

```
And anther Markdown h2 with '-'s underneath
-----------------------------------------
```

And anther Markdown h2 with '-'s underneath
-----------------------------------------


`### An h3 heading with three "###" signs`
### An h3 heading with three "###" signs

----

However, we don't recommend using Markdown for headings, as there appears to be a bug connected with their use, that removes blank lines when a section is edited. This can sometimes result in an h2 heading appearing as "## (with section title)" in the flow of the text. If this happens, change the heading to DokuWiki syntax, and insert a blank line before and after, to be sure.

If you do use Markdown headings, be sure to leave a blank space after the one or more `#` characters.

Unlike with Markdown in other places, you cannot use different text styles or links in DokuWiki, even with this plugin, because of the way DokuWiki works.

----

===== MediaWiki =====

MediaWiki markup looks like a mixture of DokuWiki and Markdown.

Mediawiki `= heading 1 =` is the same as DokuWiki `====== heading 1 ======`; Mediawiki `== heading 2 ==` is DokuWiki `===== heading 2 =====`; Mediawiki `=== heading 3 ===` is DokuWiki `==== heading 3 ====`; etc. The DokuWiki rationale seems to be that a more important heading should be more visible, hence with more `=` signs; but the MediaWiki rationale is to match the number of `=` signs with the number of the heading level. As HTML has 6 levels of heading, MediaWiki follows up from 1 to 6 =; DokuWiki counts down from 6 to 1 =. See [[MediaWiki and DokuWiki]].

===== Table of contents =====

When there are headings in a page, DokuWiki automatically provides a table of contents in the top right of the page. You should be able to see that now. Clicking on any entry in the table of contents takes you directly to that section of the page. Hover over any of the things in that table, and you will see the URL has a `#` and then a form of the section title. This is exactly the same as is used in HTML on the web.

You can fold away the table of contents by clicking at the top of it.

This means that you can link to a section in any wiki page by appending `#` and then the modified section heading text. To give an example, the URL `https://www.dokuwiki.org/wiki:syntax#sectioning` takes you to [[doku>syntax#sectioning]] in the middle of DokuWiki's syntax page. These links to section headings work both for fully spelled out URLs and for short, internal links.