Website

Less than 1 minute

Here is all the information on how the Pulsar website is built and configured.

The website itself is built using VuePress v2open in new window and the Vuepress Hope Themeopen in new window.

See the documentation there for generic items not covered in this guide.

Building the website

Prerequisites

Node.js - at least version 16 (recommended installation via nvmopen in new window).
git
pnpmopen in new window - simply run corepack enable

Clone the repository and install

The website repository is https://github.com/pulsar-edit/pulsar-edit.github.ioopen in new window. Other assets are stored on other repositories but these will be downloaded automatically.

git clone https://github.com/pulsar-edit/pulsar-edit.github.io

cd pulsar-edit.github.io

pnpm install

Running the website

Once installed there are a number of scripts available to help you develop and build the site. Just prefix each command with pnpm. e,g, pnpm dev.

`dev`

Starts a watch task that will rebuild VuePress whenever a change has been made to the included Markdown and JavaScript files. Additionally, it launches the development server to test the results in the browser.

`build`

Creates an optimized production build.

`format`

Runs Prettieropen in new window over all Markdown files included in the repository to ensure consistent formatting.

Note: This task will run automatically on every commit, so it can be ignored in most cases

`lint`

Lints all Markdown files in the repository.

Note: This task will run automatically on every commit, so it can be ignored in most cases

Notes

Whilst dev does run a watch task, not everything will be updated and some changes will require you to shut down the server and start it again. For example adding @include files to another file will not rebuild automatically.

If you wish to add new files from another repository via alias or @include then you will need to run pnpm update to get the latest version of the repository - the pnpm-lock.yml file will also be updated and must be part of any commit.

Configuration files

Nearly everything regarding the configuration of the website itself is controlled via the files found in the /docs/.vuepress directory.

Currently we have three main configuration files.

`config.js`

This is the main configuration file for the website. This controls everything from the available settings, additional VuePress plugins, website description and various other elements to control various settings and plugins.

For a full reference you can look at the documentation for VuePressopen in new window and the Hope Themeopen in new window.

This file is broken down to to keep it tidy, the below files are imported to config.js to extend the configuration file without making it unwieldy.

`navbar.js`

This controls the layout for the links in the top middle of the page and is always displayed.

Items that go here are ones that we always want to be shown and should always be available for quick navigation.

Each object can have a number of different values. The main ones we use are:

text: This sets the text for the label.
icon: Used to prefix an icon to the item. The theme supports the free FontAwesomeopen in new window font natively. To add an icon you need to specify its name without the first fa- e.g. fa-houseopen in new window would be specified as solid fa-house.
link: This controls where the link will actually take you. This can be a relative reference internal to the website or can be a URL to an external site.
children: Allows you to specify an array of child objects which will appear as a dropdown on mouseover. Use of this disables the link value. Each child can be defined as a full object as described here or can simply be a relative link from which the text will be set by the YAML title.

For a full reference you can look at the documentation for VuePressopen in new window and the Hope Themeopen in new window.

`sidebar.js`

This control what is displayed in the sidebar on the left of the website. It is not displayed globally, only on directories which are set within the sidebar, currently we only have docs configured.

Like navbar.js each sidebare item is configured as an object with a number of different values.

text: This sets the text for the label.
link: Controls the relative link for navigating the documents within the section
icon: Used to prefix an icon to the item. The theme supports the free FontAwesomeopen in new window font natively. To add an icon you need to specify its name without the first fa- e.g. fa-houseopen in new window would be specified as solid fa-house.
prefix: This adds a file path prefix to the item so its children do not need to specify the full path.
collapsable: (sic) Controls whether the item can be collapsed. Note: This a breaking change on a future version of the Hope Theme so will need to be renamed collapsible when updated, see: Issueopen in new window.
children: Takes an array of objects configured as above. Can also be set as a simple relative link in which case the title will be the YAML title of the document it links to.

For a full reference you can look at the documentation for VuePressopen in new window and the Hope Themeopen in new window.

Theme

Within the styles/ directory you will find the .scss file for controlling various aspects of the website's theme.

TODO: This will be updated when we actually modify these files extensively.

File Organization

One of the most important things to take note of when adding new documentation is where it should go within the website layout.

The generalized overall layout of the website looks like this:

docs
├── root level .md files
└── section folder
    ├── sections
    └── index.md

The general idea is that for files that can stand by themselves (for example the About Us page, Repositories etc.) they exist at the docs/ "root" level.

For anything that is more complex it needs to have a section directory named appropriately, an index.md file within it and a sections directory.

`index.md`

This index file needs to have a YAML frontmatter to define, at a minimum, the title of the document. This is displayed as an H1 header for the page (note: subsequent H1 headers will be ignored so always start at H2).

The rest of this index file will be used to display the actual content you want to show. This is done in a number of ways.

First of all you can just include standard markdown. This is often used for introducing the section or adding one of our reusable components (e.g. a danger container).

The rest of the file should consist of @includes which take data from other folders on the website and integrates it automatically. Usually this will be the sections files which will be covered next.

e.g.

@include(sections/file-organization.md)

However you can also use @include to feature files from a different section of the website or even files from outside the main site. We use this to include files which are maintained on the organization .github repoopen in new window for org-level documents.

This is done by having a value defined on the config.js file which will provide an alias for us to use:

if (file.startsWith("@orgdocs")) {
	return file.replace(
		"@orgdocs",
		path.resolve(__dirname, "../../node_modules/.github/")
	);
}

This allows us to include org-level docs by using this special alias.

e.g.

@include(@orgdocs/TOOLING.md)

Sections

The sections directory is where we include the rest of the documents broken down by section. These should be self contained files which can be used alone but are designed to be included on the section page. This approach allows us flexibility with ordering as well as including these files in other places without needing to duplicate the material.

Files here can be navigated to directly on the website but should not be linked to directly.

These files shoud not have any YAML frontmatter as they will be included and shown as text.

Assets

Assets should be uploaded to the .github repoopen in new window repository so they can be used org-wide.

An alias for this exists in config.js to access files from this repository.

alias: {
  '@images': path.resolve(__dirname, '../../node_modules/.github/images')
},

So to include an image you simply need to use the standard markdown image link along with the alias:

e.g.

![MyImage](@images/path/to/image.png)

Documentation style & reusable components

The documentation for the project should maintain a consistent style where possible. This covers a number of aspects such as writing style, naming conventions, folder structure, links etc.

All docs are currently in American English (en-US) but localization is planned.

Structure

The main structure for documentation can be seen in docs/docs. There are a number of "root" sections:

launch-manual - For the current main Pulsar documentation
packages - Currently holds wiki info from the atom package repos
resources - For other referenced docs
blog - For the website blog
atom-archive - For "as is" archived Atom documentation

Within each section is an index.md which will usually contain info about each sub-section as well as links to them. These correspond to the second level items on the sidebar.

Inside sections are the sub-sections which group more specific topics. These also have an index.md which corresponds to the third level item on the sidebar. This file is displayed on the website as a single long documenent but is actually created from a number of @include() lines which reference individual sections within the next sections directory. These should be relative to the location of index.md e.g. @include(sections/pulsar-packages.md). This file also contains the frontmatter for defining the title, language and description of the file and should also be the first level heading for the page. Here is also where you can place a container such as Under Construction to apply to the entire page.

Inside the next sections directory should be the actual content of the document. Each section should start with a second level header and should not contain any frontmatter.

Links

Internal links can just be to the header (e.g.[Structure](#structure)), this to all sections included on the parent index.md so care should be made to not create any duplicate headers.

All other links should be relative but do not need to reference the index file itself (e.g.[Installing](../getting-started#installing)) will find the heading #installing within the index file in the getting-started directory above.

Images should be added to [pulsar-assets](https://github.com/pulsar-edit/pulsar-assets) and referenced from the package imported from it. This is done via an alias on the .vuepress/config.js file which adds most of the path for you: '@images': path.resolve(__dirname, '../../node_modules/pulsar-assets/images')
so the link to your image would just be ![myImage](@images/pulsar/myImage.png "My Image").

Naming

The name of the application is Pulsar and should be capitalized as such. Whilst the website and GitHub org name is Pulsar-Edit, this should not be used within documentation outside of links to the GitHub org or website.

Operating systems should be named as such:

Linux - All GNU/Linux distributions
macOS - Apple's current operating system family
Windows - Microsoft Windows family of operating systems

This is also the order they should appear in within the tab switcher.

When using the #tabs switcher they should be in this order.

When referencing them inline then they should be abbreviated to the following, strongly emphasized and separated by a -:

Linux = LNX
macOS = MAC
Windows = WIN

To keep order consistent it should be LNX -> MAC -> WIN. If instructions: common to two then it should either be LNX/MAC, LNX/WIN -> MAC/WIN

For Linux we may sometimes need to reference particular distros or families of distributions. We currently use:

Ubuntu/Debian for all distributions based on Debian or Ubuntu
Fedora/RHEL for all distrububtions based on Fedora Linux & Red Hat Red Hat Enterprise Linux. This includes AlmaLinux, CentOS, Rocky Linux etc.
Arch - for all Arch based distributions such as Manjaro, Garuda, ArcoLinux etc.
OpenSUSE - for all OpenSUSE based distributions such as GeckoLinux

We may need to add more in the future but generally users of less popular or more technical distributions such as Gentoo or NixOS understand how to adapt to their OS from the instructions above.

Containers

Where you want to display an info, warning or tab/code switcher in the document you should use a container with the ::: syntax.

e.g.

::: tabs#filename

@tab Linux

Lorem ipsum dolor sit amet...

@tab macOS

Lorem ipsum dolor sit amet...

@tab Windows

Lorem ipsum dolor sit amet...

:::

::: tip My Helpful Tip

You might want to do X to get Y

:::

You can also find a list of currently maintained preformatted containers for various purposes at pulsar-edit.github.io/common-text-blocks.mdopen in new window.

See VuePress Hope documentationopen in new window

Writing style

TODO: Needs consensus

Blog guide

This is a guide on how to add a blog post to the website which will be shown on https://pulsar-edit.dev/article/open in new window.

We are using the Vuepress Blog Pluginopen in new window which comes as part of our Vuepress Hope Theme with some light configuration to suit our purposes.

This is all implemented in the main website repositoryopen in new window.

Writing a new post

Create a new .md file in pulsar-edit.github.io/docs/blog.
- This file should be named YYYYMMDD-<author>-<title>.md e.g 20221031-CreativeUsername-ThisIsMyBlogPost.md
The metadata displayed on the website is dependent on a number of items that are configured in the YAML frontmatter of the file. You may in theory omit any of these except the title field but it's strongly recommend that you use title, author, date, category and tag as the minimum as the others will default to false.
- Frontmatter items supported currently are:
  - title - String: The displayed title of the post, consider this as H1
  - author - String: The name of the author to be displayed.
  - date - Date (ISO 8601): Allows display of date as well as enabling sorting on the timeline, set to the same as your filename date but with hyphens (e.g. 2022-10-31).
  - category - String (multiline): Enables filtering by category, this should be based on the subject of the post e.g. release, dev log, announcement. This is a multiline field if you want to set more than one category.
  - tag - String (multiline): Enables filtering by tags, this should be based on the content of the post and areas it touches on e.g. website, editor, config.
  - sticky - Bool: Enables "pinning" on the
  - star - Bool: Enables use of the star category for any important articles we want to remain visible.
  - article - Bool: You probably won't want to use this but setting this to false will exclude this page from appearing. This is set on the "example" blog post intentionally.
An excerpt can be added to the post by creating an html comment . Anything above the comment will be treated as the excerpt and anything underneath will be the content of the post.
- We are looking at implementing an auto excerpt feature but this doesn't seem to be working on the theme at the moment, this file will be updated if and when it is available.
The rest of the post is just standard Markdown - we are currently only supporting the standard features as per the MDEnhanceopen in new window plugin but if we need more features such as GFM then please discuss and we can look at adding it to the website.
Images are supported with the standard image syntax (![myImage](./assets/myImage.png)) and should be located in the blog/assets directory. You may also use standard html <img> tags, particularly if you wish to control the displayed size of the image.
Create a PR to the repo and make it obvious it is a blog post, by including [BLOG] in the title of your PR. Please don't submit it alongside any website changes.

See example postopen in new window with everything above.

Testing locally

See building

Website "Blog" page(s)

The website itself has a number of features which the aforementioned frontmatter fields can influence.

There is a "selector" at the top of the site which currently reads All, Star, Slides, Encrypted. The only ones we use are the first two and currently the theme doesn't support configuration of this. If necessary we may be able to hide it with CSS.
Any article with Star set to true will be shown in the star category.

On the right bar are 4 counters/links and filters for Articles, Category, Tag and Timeline.
Category and Tag are used to filter articles depending on the categories submitted in the respective frontmatter fields. The Timeline allows views of blog posts over time according to the dates set in the date frontmatter field.

Questions? Suggestions

Just ask in Discord or GH Discussions and ping the @documentation team.

This is very much barebones default config so please let us know if you have any suggestions as to how we can improve it.

Website

# Building the website

# Prerequisites

# Clone the repository and install

# Running the website

# dev

# build

# format

# lint

# Notes

# Configuration files

# config.js

# navbar.js

# sidebar.js

# Theme

# File Organization

# index.md

# Sections

# Assets

# Documentation style & reusable components

# Structure

# Links

# Naming

# Containers

# Writing style

# Blog guide

# Writing a new post

# Testing locally

# Website "Blog" page(s)

# Questions? Suggestions

Building the website

Prerequisites

Clone the repository and install

Running the website

`dev`

`build`

`format`

`lint`

Notes

Configuration files

`config.js`

`navbar.js`

`sidebar.js`

Theme

File Organization

`index.md`

Sections

Assets

Documentation style & reusable components

Structure

Links

Naming

Containers

Writing style

Blog guide

Writing a new post

Testing locally

Website "Blog" page(s)

Questions? Suggestions