Skip to main content

Advanced Setup

Landing page setup

With Doks you can easily configure a landing page for your documentation, fully managed from the Ghost admin UI with no coding required.

Use this landing page to display an eye-catching hero section, call to actions, testimonials, features, FAQs, and more.

Change the routes.yaml file

First, we need to change the default routes.yaml file.

Open the theme folder and locate a file named routes-landing-page.yaml, this file configures a landing page on the home page /, and move the main documentation to /docs.

Next, open Ghost admin and go to Settings then Labs, scroll to the "Routes" section and click on the "Upload routes YAML" button, then select and upload the routes-landing-page.yaml.

If you have a multi-docs setup, make sure to edit this new routes file accordingly.
If you're self-hosting, you might need to restart your Ghost server using `ghost restart`

Creating the landing page sections

Each landing page section is represented by a normal post that has the internal tag #landing (internal tags must start with #).

The landing page sections will be displayed in a chronological order (oldest first). You can adjust the order by simply changing the "Publish date" on the post settings. You can display up to 30 sections maximum.

Following are the different section types and how to configure them:

Hero section

The hero section simply correspond to the first and oldest post that has the internal tag #landing.

Open Ghost admin and start by creating a new post, give it a catchy title, then open the post settings and add the tag #landing.

Optionally, add some text to the post content, keep it short one paragraph maximum, you can add links and other text styles to it.

Optionally, you can add a short list after the previous paragraph, this list will be displayed as a horizontal checklist, use it to show high level features for example.

Optionally, you can add up to two buttons next, the first one will be the primary CTA with an accent color background, and the second one will be the secondary CTA with gray background. Make sure there is no empty space between the two buttons.

Optionally, you can also add a feature image.

The final content should look like the following:

An example of the hero section's content

Finally, publish the post (make sure to publish on the web only, no emails). The result should look like this:

An example of a hero section

In case you need to adjust the title width (to break the title earlier for example, useful when you have a short title), go to Settings > Code injection, and paste the following code into the Site Header field (make sure to adjust the value 700px to your liking):

<style>
    .home-template #main .landing-block-1 h1 {
        max-width: 700px;
    }
</style>

By default, the section text is centered. You can add the internal tag #landing-txt-left to align it to the left (in this case the checklist will be displayed vertically):

An example of a hero section with text aligned to the left

To push the feature image to the right side, add the internal tag #landing-img-right to the post:

An example of a hero section with the feature image on the right

To push the feature image to the left side, add the internal tag #landing-img-left to the post:

An example of a hero section with the feature image on the left

By default, the feature image is displayed using a 16:9 aspect ratio, depending on how much content you have, the image might look out of proportion. To change the feature image aspect ratio you can use one of the following internal tags:

  • #landing-img-1-1 for square image
  • #landing-img-3-4 for 3:4 aspect ratio (since v2.2.0)
  • #landing-img-4-3 for 4:3 aspect ratio (since v2.2.0)
  • #landing-img-4-5 for 4:5 aspect ratio
  • #landing-img-5-4 for 5:4 aspect ratio
  • #landing-img-9-16 for 9:16 aspect ratio
  • #landing-img-16-9 for 16:9 aspect ratio (default)
An example of a hero section with a square feature image (1:1 aspect ratio)

Since v2.0.0, you can add an animation effect by adding the internal tag #landing-animation

Media sections

To create simple media sections (sections with title, short text, checklist, CTAs, and image), just repeat the same process we used previously to create the hero section, the same options are supported. The main difference is that the hero section's title has a larger font size and a gradient color and we use an h1 on the markup instead of h2.

To differentiate between the sections, you can play with image and text position (center, left, right), additionally you can also change the section's background from transparent to a light gray using the internal tag #landing-bg-alt or to a light accent color with the internal tag #landing-bg-accent.

Example of multiple media sections with different background color and image position

In case you want to remove the vertical spacing in a section (to merge it with other sections for example), you can use the internal tag #landing-no-padding.

If you want to hide the section title use the internal tag #landing-no-title.

Testimonials section

To add a testimonials section, create a new post, give it a title, then add the internal tags #landing and #landing-testimonials in the post settings.

To create a testimonial, go to the post content and create a new Product card, you can find this card by clicking on the + icon on the left side of the editor or by typing /product in the editor, then select the Product option.

The Product card option

On the product card, fill in the title, this will be the testimonial main text.
Optionally, add a description, use it to show a person's name and job title.
Optionally, enabled rating, this will show the five stars.
Optionally, upload an image, this will be used as profile picture.
In case you want the testimonial to be clickable (have an external link), enable the button option on the card, fill in the text and the URL.

An example of a product card

After publishing the post, you should see the following result:

An example of a testimonial (The link is not visible, but the block is clickable)

Repeat the process for each testimonial you have, make sure there is no empty space between the product cards. You can add as much as you want, but try to keep it less that 10 testimonials to avoid hurting the page load performance.

Example of multiple testimonials

Optionally, you can add a short paragraph to the beginning of the content (before all product cards):

Example of a testimonials section with a short paragraph

Text is always centered on this type of sections, we do not support any other type of alignments. Same thing for images.

Features section

To add a features section, create a new post, give it a title, then add the internal tags #landing and #landing-features in the post settings.

To create a feature block, go to the post content and create a new Product card. On the product card, fill in the title, this will be the feature name.
Optionally, add a short description.
Optionally, upload an image, square icon images works best (make sure the icon works for both light and dark theme).
In case you want the feature block to be clickable (have an external link), enable the button option on the card, fill in the text and the URL.

Repeat the process for each feature you have, make sure there is no empty space between the product cards.

Optionally, you can add a short paragraph to the beginning of the content (before all product cards).

After publishing the post, you should see the following result:

Example of a features section

Text is always centered on this type of sections, we do not support any other type of alignments. Same thing for images.

FAQs section

To add a FAQs section, create a new post, give it a title, then add the internal tag #landing in the post settings.

To create a Q&A block, go to the post content and create a new Toggle card. On the toggle card, fill in the title and the description.

The Toggle card option

Repeat the process for each Q&A you have, make sure there is no empty space between the toggle cards.

Optionally, you can add a short paragraph to the beginning of the content (before all toggle cards).

After publishing the post, you should see the following result:

Example of a FAQs section

Text is always centered on this type of sections, we do not support any other type of alignments. Same thing for images.

Each landing page section has an HTML id equal to the section's slug (post URL).

For example, the "Frequently asked questions" section has a slug and id equal to "frequently-asked-questions".

To link to that section from another section's CTA button, set the button's URL to #frequently-asked-questions (it should #slug). If you change the section's slug later, remember to update the button's URL.

By default, we enabled smooth scrolling on this page, if you like to disable it inject the following code in Settings > Code injection > Site Header :

<style> :root { scroll-behavior: auto; } </style>

Options reference

Here you can find a quick reference to all supported options and tags:

  • #landing — Make a post a landing page section
  • #landing-txt-left — Align the section text to the left (useful when you want the text to the left but a full width image)
  • #landing-img-right — Align the section image to the right (the text will be aligned to the left automatically)
  • #landing-img-left — Align the section image to the left (the text will will be aligned to the right automatically)
  • #landing-img-1-1 — for square section image (1:1 aspect ration)
  • #landing-img-3-4 — section image with 3:4 aspect ratio (since v2.2.0)
  • #landing-img-4-3 — section image with 4:3 aspect ratio (since v2.2.0)
  • #landing-img-4-5 — section image with 4:5 aspect ratio
  • #landing-img-5-4 — section image with  5:4 aspect ratio
  • #landing-img-9-16 — section image with  9:16 aspect ratio
  • #landing-img-16-9 — section image with  16:9 aspect ratio (default)
  • #landing-bg-alt — change the section's background color to a light gray
  • #landing-bg-accent — change the section's background color to a light accent color
  • #landing-no-padding — remove the section's vertical padding
  • #landing-no-title — Hide the section title
  • #landing-testimonials — Create a testimonials section
  • #landing-features — Create a features section
  • #landing-animation — Enable animation on the current block (since v2.0.0)