ViteFolio

ViteFolio is a portfolio and academic pages template powered by Vue and VitePress.

Getting Started

Create a new repository using this template.

Click "Use this template" button top right.
Enter your repository name as {username}.github.io (optional).

If {username}.github.io is used as repository name, then that is your site's domain.
Enable GitHub Pages with source GitHub Actions.

Settings -> Pages -> Build and Deployment -> Source -> GitHub Actions.
Check deployment status at the Actions tab.

You might need a rerun due to GitHub Actions not yet being enabled.
Access the deployed site on your browser.

https://{username}.github.io if step 2, else https://{username}.github.io/{repository}.

Local Development

Environment requirements:
- Git
- Node.js LTS
For Windows users, ensure that both Git and Node.js is added to PATH during the install process.

Clone your repository:

git clone https://github.com/{username}/{repository} {foldername}

Install dependencies:
```
npm install
```
Start development server:
```
npm run dev
```
Access localhost on your browser.
```
http://localhost:5173/
```
Deploy your new changes.
```
git push origin master
```
Wait for GitHub Action to build.

Site Configuration

The configuration file is located at src/.vitepress/config.mts.

VitePress configuration:

Metadata
- Title
- Description
- Favicon
- Fonts
- Google Analytics
- Service workers
- Language
Theme
- i18nRouting
- logo
- siteTitle
- nav
- sidebar
- aside
- outline
- socialLinks
- footer
- editLink
- lastUpdated
- algolia
- carbonAds
- docFooter
- darkModeSwitchLabel
- lightModeSwitchTitle
- darkModeSwitchTitle
- sidebarMenuLabel
- returnToTopLabel
- langMenuLabel
- externalLinkIcon

ViteFolio configuration:

Theme (extends VitePress Theme)

sidebar

Must be equal to [{ text: '' }] to force an empty sidebar for your profile.

export default {
    themeConfig: {
        sidebar: [{ text: '' }], // DO NOT DELETE force an empty sidebar
    }
}

profile

title: An extra title below your avatar. Optional.
bio: Short bio or tag line.
avatar: Asset link to your avatar.
links: Array of { icon: string, href: string, text?: string }.
- icon:
  - 'discord'
  - 'facebook'
  - 'github'
  - 'instagram'
  - 'linkedin'
  - 'mastodon'
  - 'npm'
  - 'slack'
  - 'twitter'
  - 'x'
  - 'youtube'
  - { svg: '<svg ...>...</svg>' }
- href: Link to social website.
- text: Display text. Optional, default to last path param of href.

export default {
    themeConfig: {
        profile: {
            title: '', // hidden if empty
            bio: "Short biography for the left-hand sidebar",
            avatar: 'https://www.github.com/iann838.png',
            links: [
                { icon: 'github', link: 'https://github.com/iann838' },
                { icon: 'x', link: 'https://x.com/iann838' },
                // { icon: { svg: '<svg >...</svg>' }, link: '...' }
            ]
        }
    }
}

Link Routing

Internal links are converted to router link for navigation. Also, every index.md contained in each sub-directory will automatically be converted to index.html, with corresponding URL /.

For example, given the following directory structure:

.
├─ src
.  ├─ index.md
.  ├─ foo
.  │  ├─ index.md
   │  ├─ one.md
   │  └─ two.md
   └─ bar
      ├─ index.md
      ├─ three.md
      └─ four.md

And providing you are in foo/one.md:

[Home](/) <!-- sends the user to the root index.md -->
[foo](/foo/) <!-- sends the user to index.html of directory foo -->
[foo heading](./#heading) <!-- anchors user to a heading in the foo index file -->
[bar - three](../bar/three) <!-- you can omit extension -->
[bar - three](../bar/three.md) <!-- you can append .md -->
[bar - four](../bar/four.html) <!-- or you can append .html -->

Pages and internal links get generated with the .html suffix by default.

Public Directory

Static assets that are not directly referenced in any of your Markdown or theme components, or you may want to serve certain files with the original filename. Examples of such files include robots.txt, favicons, PDFs, videos, audio, images, media files.

You can place these files in the public directory under the src directory. Assets placed in public will be copied to the root of the output directory as-is.

Note that you should reference files placed in public using root absolute path - for example, public/example-file.txt should always be referenced in source code as /example-file.txt.

<VFDownload text='Download Paper' href='/example-file.txt' as='publication-a.txt'/> 
<!-- Download button for file at `public/example-file.txt` -->

When adding files or making changes to the public directory, you might need to do a cold deep reload on your site using Ctrl F5, as the browser might be caching old responses for these files.

Vue Components

You can use HTML tags or Vue components in markdown files.

ViteFolio has 2 extra grobally imported components:

<VFDownload />
- text=: Display text of your download button.
- href=: URL of the download resource.
- as=: The default filename to be saved as for the download.
- theme=: One of brand | alt | sponsor. Default: brand.
- size=: One of medium | big. Default: medium.
<VPButton />
- text=: Display text of your button
- href=: URL to route the user to. Can be local or external.
- theme=: One of brand | alt | sponsor. Default: brand.
- size=: One of medium | big. Default: medium.

"Download Paper" button example:

<VFDownload
    text='Download Paper'
    href='/example-file.txt'
    as='publication-a.txt'
/>

Markdown Extensions

List of markdown extensions supported by the VitePress engine.

Custom domain

You may use a custom domain for your site by going to Settings -> Pages -> Custom domain. After entering your custom domain, ensure that the required CNAME DNS records are also created correctly on your DNS provider.

CNAME <recordname> <githubusername>.github.io

Sitemap generation

A sitemap is a file where you provide information about the pages, videos, and other files on your site, and the relationships between them. Search engines like Google read this file to crawl your site more efficiently.

VitePress will automatically generate a sitemap file at /sitemap.xml after building. Replace the sitemap hostname on your config file to ensure the sitemap content is correct.

export default {
    sitemap: {
        // REPLACE this with your hosted URL for sitemap to work!
        hostname: 'https://yourhosteddomain.com',
    }
}

Star me!

Star this repo if you find it helpful!

iann838/vitefolio