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

1. Clone the repository:

$ git clone https://github.com/Penify-dev/Penify-usage-doc-site
$ cd Penify-usage-doc-site

2. Install Yarn Packages:

$ yarn install

3. 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

1. Create a new Markdown file in the docs directory.

2. Add content (html or md syntax) to this markdown file.

Building for production

1. To build site for production, run:

yarn docs:build

The build files will be available in the .vitepress/dist directory.

2. 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:

1. Create a Supabase account and start a new project

2. Get your Supabase URL and anon key from the project settings:

   • Go to Project Settings > API
   • Copy the URL and anon key

3. Update the .vitepress/lib/supabaseClient.ts file with your credentials:

   const supabaseUrl = "your-supabase-url"
   const supabaseAnonKey = "your-anon-key"

4. Set up a table for email subscriptions in Supabase:

   CREATE TABLE email_subscriptions (
     id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
     email TEXT UNIQUE NOT NULL,
     created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
   );

5. Add Row Level Security (RLS) policies:

   -- 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:

1. Create a public GitHub repository for hosting discussions (or use an existing one)

2. Enable GitHub Discussions in the repository:

   • Go to your repository settings
   • Scroll down to "Features"
   • Enable "Discussions"

3. Install the Giscus app on your repository

4. 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

5. Update the Giscus configuration in .vitepress/theme/Comments.vue:

   script.dataset.repo = 'your-username/your-repo'  
   script.dataset.repoId = 'your-repo-id'
   script.dataset.category = 'Your Category'
   script.dataset.categoryId = 'your-category-id'

6. Import and use the Comments component in your theme layout:

   <template>
     <div class="content">
       <!-- Your content -->
       <Comments v-if="$frontmatter.comments !== false" />
     </div>
   </template>
   
   <script setup>
   import Comments from './Comments.vue'
   </script>

7. To disable comments on specific pages, add comments: false to the frontmatter.

Environment Variables

For security, store sensitive values in environment variables:

1. Create a .env file in the project root:

VITE_SUPABASE_URL=your-supabase-url
VITE_SUPABASE_ANON_KEY=your-supabase-anon-key

2. 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

3. Add .env to your .gitignore file to prevent committing sensitive data