Modifying Content on VitePress

VitePress

See the official documentation

Pull Requests: Before opening a pull request, please check if the project builds successfully with npm run docs:build. Some issues will not be caught by the development server, but this command will catch them.

Using the installed plugins

Iconify

We are using Iconify to display icons on the site.

1. Find an icon from their website
   • For most cases, you will need to set it to Vue and copy the code.
   • In some cases, such as the Vitepress Style Cards below, you will need to copy the short code only.
2. Use the icon with text as follows:

<h3 class="text-with-icon">
    <Icon icon="ci:folders" width="1.2em" height="1.2em" />
    Relevant Projects
</h3>

Customization:

• You can use the icon-left, icon-right, and icon-middle classes to change the position of the icon. For example: <h3 class="text-with-icon icon-right">.
• You can change other properties of the icon by using the menus on the Iconify website.

Note

Custom Components Before you can use icons in custom components, you need to add the following code:

<script>
import { Icon } from "@iconify/vue"; // [!code ++]
// ...

export default {
  // ...
  components: {
    Icon, // [!code ++]
  },
  // ...
}

Medium Zoom

We are using Medium Zoom to allow for zooming in on images. You can see it in action in the 'warning messages' section on this page.

To use it, you need to add the data-zoomable attribute to the image you want to zoom in on. For example:

![image](/img/campus/ubc-sights/blossoms.jpg){ data-zoomable }

Using our Custom Components

ImageText.vue (Section with images & text)

To use it, you can copy the following code:

<ImageText
  image-link="/img/campus/ubc-sights/blossoms.jpg"
  zoomable
  input="This can be a long paragraph of text."
></ImageText>

Tip

More Information

• image-link - Path to the image you want to display. You should place your image in the docs/src/public/img directory corresponding to the section you are working on.
• zoomable (optional) - Allows the image to be zoomed in on.
• input - The text that will be displayed on the right side of the image.
• image-size (optional) - Set the width of the image in px. The default is 200px.
• placement (optional) - Determines the placement of the image and text. The default is left (image on the left, text on the right).
• margin (optional) - Determines the margin in px between the image and text. The default is 20px.

Card.vue & CardContainer.vue (cards with banner images)

These cards should be used listing resources from other websites. It will likely NOT be used much on this project as we want to minimize external resources, if at all.

To use them, you can copy the following code:

<CardContainer>
    <Card 
        title="Example Card"
        image="/img/card-tools.jpg"
        description="This is a description of the card. Try to keep it within 2 lines."
        link="https://example.com"
        :tags="['Course Difficulty', 'GPA']"
    />
    <!-- copy this card as many times as you need -->
</CardContainer>

Tip

More Information

You can use the other sections of the site as a reference for how to use these cards.

Card:

• image - Path to the image you want to display on the card. You should place your image in the docs/src/public/img directory corresponding to the section you are working on.
• link - URL that the card will take the user to when clicked
• tags - An array of strings that will be displayed on the card as pill shaped tags
• disabled (optional) - Causes the card to be greyed and unclickable.

CardContainer:

• :cols (optional) - Sets the number of columns in the card container: <CardContainer :cols="2">.

VitepressCard.vue & VitepressCardContainer.vue

These cards should be used when displaying a list of links to pages on this site. You can see the cards on the homepage.

To use them, you can copy the following code:

<VitepressCardContainer :cols="2">
  <VitepressCard
    icon="material-symbols:image-outline"
    iconColor="#123456"
    title="Example Card"
    body="This is a description of the card. Try to keep it within 2 lines."
    link="./page"
    linkText="Jump to section"
  />
  <!-- copy this card as many times as you need -->
</VitepressCardContainer>

Tip

More Information

You can use the other sections of the site as a reference for how to use these cards.

VitepressCard:

• icon (optional) - The icon that will be displayed on the card. You can icon codes from here.
• iconColor (optional) - The colour of the icon, represented as a hex code.
• link (optional) - The relative location of the page you are linking to.
• linkText (optional) - The text that will be displayed on the link

VitepressCardContainer:

• :cols (optional) - Sets the number of columns in the card container: <CardContainer :cols="2">.

Creating Components

You can see our components in the docs/.vitepress/theme/components directory. These components can be reused across the site.

1. Create a new .vue file in the docs/.vitepress/theme/components directory. See the Official Vue.js documentation for more information on how to create components.
2. Update docs/.vitepress/theme/index.ts to include the new component. For example:

import MyNewComponent from './components/MyNewComponent.vue'; // [!code ++]
// ...
export default {
  // ...
  enhanceApp({ app, router, siteData }) {
    app.component('MyNewComponent', MyNewComponent); // [!code ++]
  },
  // ...
} satisfies Theme