Penify Documentation Site β
Welcome to the Penify Documentation Site, powered by VitePress. This guide will help you on how to get started with vitepress, a vue powered static site generator.
Prerequisites β
- Node.js (20.x)
- Yarn
- Basic knowledge of Vue.js and Markdown
Installation β
- Clone the repository:
$ git clone https://github.com/Penify-dev/Penify-usage-doc-site
$ cd Penify-usage-doc-site
- Install Yarn Packages:
$ yarn install
- Run the development server:
$ yarn docs:dev
This will start local development server on port 3000. The site should now be running on http://localhost:3000/
Create your first page β
Create a new Markdown file in the
docs
directory.Add content (html or md syntax) to this markdown file.
Building for production β
- To build site for production, run:
yarn docs:build
The build files will be available in the .vitepress/dist
directory.
- To preview the production build, run:
yarn docs:preview
This will serve the production build locally for testing.
Configuring Supabase β
Supabase is used for storing user data like newsletter subscriptions. Here's how to set it up:
Create a Supabase account and start a new project
Get your Supabase URL and anon key from the project settings:
- Go to Project Settings > API
- Copy the URL and anon key
Update the
.vitepress/lib/supabaseClient.ts
file with your credentials:typescriptconst supabaseUrl = "your-supabase-url" const supabaseAnonKey = "your-anon-key"
Set up a table for email subscriptions in Supabase:
sqlCREATE TABLE email_subscriptions ( id UUID DEFAULT uuid_generate_v4() PRIMARY KEY, email TEXT UNIQUE NOT NULL, created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW() );
Add Row Level Security (RLS) policies:
sql-- Enable RLS ALTER TABLE email_subscriptions ENABLE ROW LEVEL SECURITY; -- Create policy for inserting emails (anyone can subscribe) CREATE POLICY "Anyone can subscribe" ON email_subscriptions FOR INSERT WITH CHECK (true); -- Create policy for viewing emails (only authenticated users with specific roles) CREATE POLICY "Only admins can view subscribers" ON email_subscriptions FOR SELECT USING (auth.role() = 'authenticated' AND auth.email() IN ('admin@example.com'));
Setting Up Giscus Comments β
Giscus is a comments system powered by GitHub Discussions. Follow these steps to set it up:
Create a public GitHub repository for hosting discussions (or use an existing one)
Enable GitHub Discussions in the repository:
- Go to your repository settings
- Scroll down to "Features"
- Enable "Discussions"
Install the Giscus app on your repository
Configure Giscus:
- Visit https://giscus.app/
- Enter your repository name (format: username/repo)
- Choose the discussion mapping (recommended: "Discussion title contains page pathname")
- Select a discussion category (create one if needed)
- Copy the generated configuration values
Update the Giscus configuration in
.vitepress/theme/Comments.vue
:vuescript.dataset.repo = 'your-username/your-repo' script.dataset.repoId = 'your-repo-id' script.dataset.category = 'Your Category' script.dataset.categoryId = 'your-category-id'
Import and use the Comments component in your theme layout:
vue<template> <div class="content"> <!-- Your content --> <Comments v-if="$frontmatter.comments !== false" /> </div> </template> <script setup> import Comments from './Comments.vue' </script>
To disable comments on specific pages, add
comments: false
to the frontmatter.
Environment Variables β
For security, store sensitive values in environment variables:
- Create a
.env
file in the project root:
VITE_SUPABASE_URL=your-supabase-url
VITE_SUPABASE_ANON_KEY=your-supabase-anon-key
- Update
supabaseClient.ts
to use these environment variables:
const supabaseUrl = import.meta.env.VITE_SUPABASE_URL
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY
- Add
.env
to your.gitignore
file to prevent committing sensitive data