Planum Docs
LINKS
  • Home
  • GitHub Repository
DOCS
  • Installation Guide
  • Getting Started
  • Writing your First Doc
  • Configuration

    • App Configuration
    • Sidebar Configuration
  • Deploying to Production
    • Markdown Cheat Sheet
    • Using Math in Planum
v2.0.0 Docs

Getting started

Congratulations on setting up Planum Docs! This page will help you get started with the project.

Directory Structure

Here is the directory structure of Planum Docs:

Path: /
public/ # static assets src/ # source code, don't need to touch src/config/ # configuration files src/content/ # docs
  • config: Contains configuration files for the project. You can change the website name, logo, and other settings from here.
  • content: This is where you will be adding your docs and folders.
  • public: Contains static assets such as images, stylesheets, and scripts.
  • src: Contains the source code of the project. You don't need to touch this directory unless you want to change how Planum works.

Home Page

The home page is pages/index.md file. Feel free to edit this file to add your content. You can also change the layout of the home page by editing layouts/IndexLayout.astro.

Creating Docs and Folders

Location

The docs are to be stored in the content/{version} directory. You may make directories inside as well.

Versioning

Versioning is enabled by default. Simply make a directory like v2.0 inside content and start adding your docs there.

You also need to update the src/content/config.ts file to add the new version.

src/content/config.ts
export const versions = [ { name: 'version_name', homepage: 'homepage_filename' // directly within the version folder }, ];

Simply change the values of name and homepage as required. To add new version, copy content inside { } including brackets and paste it above.

src/content/config.ts
export const versions = [ { name: 'new_version_name', // new version homepage: 'new_homepage_filename' }, { name: 'version_name', homepage: 'homepage_filename' }, ];

This array is in ascending order, where the first element is the latest version and the last element is the oldest version.

Naming Convention

Use this format to name your files:

Doc_A.md        # doc
Some_Directory  # directory
_Doc_D.md       # draft, is hidden

Here are the three rules that apply:

  1. File and directory names act as slug in the URL, and these are case-sensitive. For files .md extension is removed and is replaced with .html. For directories, the name is used as is.

  2. Files starting with _ (underscore) are seen as a draft and are hidden inside the navigation tree.

  3. When naming a file or folder:

    • Do not to use spaces.
    • Use these URL safe symbols -_.!'().
    • Use only English (A-Z a-z) and numerical (0-9) characters.

    None of the above are strict rules, but following them will make your life easier when linking docs.

    Not Recommended Recommended
    Doc A.md Doc_A.md
    Some Directory Name Some_Directory_Name

    When using spaces and special characters other than -_.!'(), you should be cautious to how you link other docs.

    [Link to Doc A](Doc_A.md)  # works
    [Link to Doc A](Doc A.md)  # doesn't work

    To make it work, you will have to replace the spaces with %20:

    [Link to Doc A](Doc%20A.md) # works although not very readable

    For character encoding reference, see W3 Schools - URL Encoding.

Previous
Installation Guide
Next
Writing your First Doc
TABLE OF CONTENTS
  • Directory Structure
  • Home Page
  • Creating Docs and Folders
  • Location
  • Versioning
  • Naming Convention