DevTeam

Dev Team documentation/knowledge repository

Contributing

Requirements

• System Git (Git for Windows)

winget install --id Git.Git -e --source winget

Getting started

Clone the repo

Clone with SSH

git@gitlab.com:ticketsource/devteam.git

Clone with HTTPS

https://gitlab.com/ticketsource/devteam.git

Install build tools

From the project root:

npm install

Running a local version

npm run docs:dev

This will spin up a local development server with a localhost url that you can copy and paste or press o to open it directly in your default browser.

Pages

Pages live in the /src directory and it's child directories.

Structure

The web root (i.e. https://devteam.ticketsource.com) maps to the /src directory and the path will map to any of it's child directories.

Inbound URLs don't need to specify an extension if the final path segment is a directory it will map to a index.md file otherwise it will map to a markdown file that matches the segment.

URL Path	Maps to:
/	/src/index.md
/reference	/src/reference/index.md
/help/vitepress/markdown	/src/help/vitepress/markdown.md

NOTE

Currently we use index.md for the parent page for a directory or section (e.g. /src/reference/index.md) then named .md files for specific pages (e.g. /src/reference/audience-agency.md).

Content

All pages are markdown (.md) files and can be as simple as:

# Page title

Lorem Ipsum...

All standard markdown can be used and VitePress provides some extensions for advanced usage.

Frontmatter/Metadata

You can configure metadata/head content for a page by providing yaml formatted frontmatter at the top of markdown pages. This can also be used to configure individual display options for pages such as toggling the sidebar/aside, changing the depth of the auto generated aside navigation and even adding custom classes to individual pages to be targeted by css rules in /.vitepress/theme/custom.css.

Examples of most of the frontmatter options available can be found in the raw markdown of this page and you can view the VitePress frontmatter guide and reference for more information.

Navigation

Navigation is configured in the .vitepress/config.mts file which exposes site configuration as a js object.

Navigation can be found within the themeConfig property:

export default defineConfig({
  // Site Metadata
  title: 'TS Dev Portal',
  titleTemplate: 'TS Dev Portal',
  description: 'The TS Dev Team Portal',
  lang: 'en-GB',
  base: '/',
  // Routing
  cleanUrls: true,
  // Build
  srcDir: "./src",
  // Theming
  appearance: true,
  lastUpdated: true,
  // Theme configuration
  themeConfig: { 
    ...
  },
})

Nav (Top Bar)

The top navigation can be configured under the themeConfig.nav property which is an array of objects with each object representing a NavItem. NavItem objects have a text property and either a link property or an items property. The items property is a recursive array of further NavItem objects and can be used to build nested navigation.

Sidebars

The sidebars can be configured under the themeConfig.sidebar property, the syntax is virtually identical to the top bar (nav) however to top level keys (see highlighted lines in the example below) are a regex match against the path of a page and is used to display different sidebars on different sections of the site.

Examples

nav (top bar)

...
nav: [
    { 
        text: 'Reference',
        link: '/reference',
    },
    ...
    { 
        text: 'Help',
        items: [
            {
                text: 'Contributing',
                link: '/help/contributing',
            },
            {
                text: 'VitePress',
                items: [
                    {
                    text: 'Markdown Extensions',
                    link: '/help/vitepress/markdown',
                    }
                ]
            },
        ],
    },
],
...

sidebar

...
sidebar: {
    '/reference/': [
        {
            text: 'Reference',
            items: [
                { text: 'Audience Agency', link: '/reference/audience-agency' },
                { text: 'Maps', link: '/reference/maps'},
            ],
        },
    ],
    '/fixes/': ...
}
...

Production

Infrastructure

• Deployed via Cloudflare Pages: devteam
  • Build command: npx vitepress build
  • Output directory: .vitepress/dist

Deploying

Commits to the main branch will be picked up by the Cloudflare Worker deployment script

Troubleshooting

You can attempt a local build using the following command:

npm run docs:build