devfolio-page 0.1.0

package/README.md

@@ -0,0 +1,219 @@
+# devfolio.page
+
+> Your portfolio as code. Version control it like software.
+
+## Installation
+
+```bash
+npm install -g devfolio-page
+```
+
+## Quick Start
+
+```bash
+# Create a new portfolio folder
+devfolio-page init
+
+# Edit the portfolio config
+cd my-portfolio
+nano portfolio.yaml
+
+# Generate the static site
+devfolio-page render
+
+# Open in browser
+open site/index.html
+```
+
+## Folder Structure
+
+After running `devfolio-page init`, you get:
+
+```
+my-portfolio/
+├── portfolio.yaml   # Your config
+├── images/          # Add images here
+└── site/            # Generated after render
+    ├── index.html
+    └── assets/
+```
+
+## Commands
+
+### `devfolio-page init`
+
+Create a new portfolio folder with config and images directory.
+
+```bash
+devfolio-page init
+```
+
+### `devfolio-page render`
+
+Generate a static website. Run from inside your portfolio folder.
+
+```bash
+devfolio-page render                        # Uses portfolio.yaml → site/
+devfolio-page render --theme modern         # Use a different theme
+devfolio-page render --output ./dist        # Custom output directory
+devfolio-page render other.yaml             # Use a different YAML file
+```
+
+**Options:**
+
+- `-t, --theme <theme>` - Theme to use (srcl, modern, dark-academia)
+- `-o, --output <dir>` - Output directory (default: ./site)
+
+### `devfolio-page validate <file>`
+
+Validate your portfolio YAML file.
+
+```bash
+devfolio-page validate portfolio.yaml
+```
+
+## YAML Schema
+
+```yaml
+meta:
+  name: Your Name
+  title: Your Title
+  location: Your Location
+  timezone: America/Los_Angeles  # optional
+
+contact:
+  email: you@example.com
+  github: username        # optional
+  linkedin: username      # optional
+  twitter: username       # optional
+  website: https://...    # optional
+
+bio: |
+  A few sentences about yourself.
+  Can be multiple lines.
+
+sections:
+  experience:
+    - company: Company Name
+      role: Your Role
+      date:
+        start: 2024-01
+        end: present
+      location: City, State  # optional
+      highlights:
+        - Achievement 1
+        - Achievement 2
+
+  projects:
+    - name: Project Name
+      url: https://github.com/...  # optional
+      description: What the project does
+      tags: [React, TypeScript]
+      featured: true  # optional
+
+  skills:
+    Frontend: [React, TypeScript, Next.js]
+    Backend: [Node.js, Python, Go]
+    Tools: [Git, Docker, AWS]
+
+  writing:
+    - title: Article Title
+      url: https://...
+      date: 2024-12
+      description: Brief description  # optional
+
+  education:
+    - institution: University Name
+      degree: B.S. Computer Science
+      date:
+        start: 2016-09
+        end: 2020-05
+      location: City, State  # optional
+      highlights:  # optional
+        - Dean's List
+        - Relevant coursework
+
+theme: srcl  # srcl, modern, dark-academia
+
+settings:
+  show_grid: false       # show character grid overlay
+  enable_hotkeys: true   # enable keyboard shortcuts
+  color_scheme: dark     # dark or light
+  animate: subtle        # none, subtle, or full
+```
+
+## Themes
+
+### SRCL (Default)
+
+Terminal-inspired aesthetic from [sacred.computer](https://sacred.computer).
+
+- Monospace typography
+- Character-based spacing
+- Keyboard navigation (Ctrl+T, Ctrl+G)
+- Dark/light mode toggle
+
+### Modern
+
+Clean, contemporary design.
+
+- Sans-serif fonts
+- Card-based layout
+- Smooth animations
+
+### Dark Academia
+
+Classical, scholarly design.
+
+- Serif typography
+- Warm color palette
+- Book-like layout
+
+## Keyboard Shortcuts
+
+When `enable_hotkeys: true`:
+
+| Key | Action |
+|-----|--------|
+| `Ctrl+T` | Toggle dark/light theme |
+| `Ctrl+G` | Toggle grid overlay |
+| `1-9` | Jump to section |
+| `Esc` | Close accordions |
+
+## Philosophy
+
+Inspired by [RenderCV](https://github.com/sinaatalay/rendercv). Your portfolio should be:
+
+- **Version controlled** - Track changes with Git
+- **Content-first** - Separate content from presentation
+- **Portable** - Deploy anywhere (Vercel, Netlify, GitHub Pages)
+- **Fast** - Static HTML, no JavaScript required
+- **Accessible** - Semantic HTML, keyboard navigation
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in dev mode
+npm run dev
+
+# Build
+npm run build
+
+# Link globally for testing
+npm link
+```
+
+## Examples
+
+See the `examples/` directory:
+
+- `minimal.yaml` - Bare minimum required fields
+- `full.yaml` - All sections and options
+- `engineer.yaml` - Realistic software engineer example
+
+---
+
+Built with [SRCL](https://sacred.computer).

package/dist/cli/commands/init.js

@@ -0,0 +1,282 @@
+import chalk from 'chalk';
+import * as readline from 'readline';
+import { writeFileSync, existsSync, mkdirSync } from 'fs';
+import path from 'path';
+const THEMES = [
+    {
+        id: 'srcl',
+        name: 'SRCL',
+        description: 'Terminal aesthetic with monospace fonts',
+        example: 'https://devfolio.page/portfolios/engineer-srcl/',
+    },
+    {
+        id: 'modern',
+        name: 'Modern',
+        description: 'Clean, contemporary design',
+        example: 'https://devfolio.page/portfolios/designer-modern/',
+    },
+    {
+        id: 'dark-academia',
+        name: 'Dark Academia',
+        description: 'Scholarly, vintage aesthetic',
+        example: 'https://devfolio.page/portfolios/researcher-academia/',
+    },
+];
+function createInterface() {
+    return readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+}
+function question(rl, prompt) {
+    return new Promise((resolve) => {
+        rl.question(prompt, (answer) => {
+            resolve(answer.trim());
+        });
+    });
+}
+function printHeader() {
+    console.log();
+    console.log(chalk.cyan('┌────────────────────────────────────────┐'));
+    console.log(chalk.cyan('│') + ' Welcome to ' + chalk.bold('devfolio.page') + '!                   ' + chalk.cyan('│'));
+    console.log(chalk.cyan('│') + ' Let\'s create your portfolio            ' + chalk.cyan('│'));
+    console.log(chalk.cyan('└────────────────────────────────────────┘'));
+    console.log();
+    console.log('This will create a portfolio folder with your YAML config.');
+    console.log('You can add projects, experiments, and writing later.');
+    console.log();
+}
+function generateYaml(input) {
+    return `# Portfolio configuration for devfolio.page
+# Run: devfolio render (from this folder)
+
+meta:
+  name: ${input.name}
+  title: ${input.title}
+  location: ${input.location}
+  # avatar: /images/avatar.jpg
+  # hero_image: /images/hero.jpg
+
+contact:
+  email: ${input.email}
+  ${input.website ? `website: ${input.website}` : '# website: https://yoursite.com'}
+  ${input.github ? `github: ${input.github}` : '# github: yourusername'}
+  ${input.linkedin ? `linkedin: ${input.linkedin}` : '# linkedin: yourusername'}
+  ${input.twitter ? `twitter: ${input.twitter}` : '# twitter: yourusername'}
+
+bio: |
+  Write a brief introduction about yourself here.
+  What do you do? What are you passionate about?
+
+about:
+  short: |
+    A brief description about yourself. This shows on the homepage.
+
+  long: |
+    ### Background
+
+    Tell your story here. Use markdown formatting.
+
+    ### What I Do
+
+    Describe your work and expertise.
+
+    ### Interests
+
+    Share what drives you.
+
+# Add your projects here
+# Each project can have multiple sections: overview, images, code, demos, etc.
+projects:
+  - id: example-project  # URL slug
+    title: Example Project
+    subtitle: A brief description
+    featured: true  # Show on homepage
+
+    thumbnail: /images/projects/example/thumbnail.png
+    # hero: /images/projects/example/hero.png
+
+    meta:
+      year: 2024
+      role: Solo Developer
+      timeline: 2 weeks
+      tech: [React, TypeScript]
+      links:
+        github: https://github.com/yourusername/project
+        # demo: https://project-demo.com
+
+    sections:
+      - type: overview
+        content: |
+          ## The Problem
+
+          Describe the problem you solved.
+
+          ## The Solution
+
+          Explain your approach.
+
+      # Add more sections: image, gallery, code, metrics, etc.
+      # See documentation for all section types
+
+# Add side projects and experiments
+experiments:
+  - title: Cool Experiment
+    description: A fun side project
+    # image: /images/experiments/cool.png
+    github: https://github.com/yourusername/experiment
+    tags: [javascript, fun]
+
+sections:
+  # Add your work experience
+  experience:
+    - company: Company Name
+      role: Your Role
+      date:
+        start: 2024-01
+        end: present
+      location: City, Country
+      highlights:
+        - Achievement 1
+        - Achievement 2
+
+  # Add your skills by category
+  skills:
+    Languages: [TypeScript, Python]
+    Tools: [Git, Docker]
+
+  # Add articles or blog posts
+  writing:
+    - title: Blog Post Title
+      url: https://yourblog.com/post
+      date: 2024-12
+      excerpt: A brief excerpt of the post
+      # cover: /images/writing/post.png
+      tags: [tech, tutorial]
+      featured: true
+
+  # Add your education (optional)
+  # education:
+  #   - institution: University Name
+  #     degree: B.S. Computer Science
+  #     date:
+  #       start: 2016-09
+  #       end: 2020-05
+
+# Choose your theme
+theme: ${input.theme}  # or: srcl, modern, dark-academia
+
+# Configure layout
+layout:
+  homepage_style: hero  # or: grid, minimal
+  project_layout: case-study  # or: grid, list
+  show_experiments: true
+  show_timeline: false
+
+settings:
+  show_grid: false
+  enable_hotkeys: true
+  color_scheme: dark
+  animate: subtle
+`;
+}
+export async function initCommand() {
+    printHeader();
+    const rl = createInterface();
+    try {
+        // Ask for folder name first
+        let folderName = await question(rl, chalk.cyan('? ') + 'Portfolio folder name? ' + chalk.dim('(portfolio) '));
+        if (!folderName) {
+            folderName = 'portfolio';
+        }
+        if (existsSync(folderName)) {
+            console.log(chalk.red('✗') + ` ${folderName}/ already exists`);
+            console.log(chalk.dim('  Choose a different name or delete the existing folder'));
+            rl.close();
+            process.exit(1);
+        }
+        const name = await question(rl, chalk.cyan('? ') + 'What\'s your name? ');
+        if (!name) {
+            console.log(chalk.red('✗') + ' Name is required');
+            process.exit(1);
+        }
+        const title = await question(rl, chalk.cyan('? ') + 'What\'s your title/role? ');
+        if (!title) {
+            console.log(chalk.red('✗') + ' Title is required');
+            process.exit(1);
+        }
+        const location = await question(rl, chalk.cyan('? ') + 'Where are you located? ');
+        if (!location) {
+            console.log(chalk.red('✗') + ' Location is required');
+            process.exit(1);
+        }
+        const email = await question(rl, chalk.cyan('? ') + 'What\'s your email? ');
+        if (!email) {
+            console.log(chalk.red('✗') + ' Email is required');
+            process.exit(1);
+        }
+        // Theme selection
+        console.log();
+        console.log(chalk.cyan('? ') + 'Which theme would you like?');
+        console.log();
+        THEMES.forEach((theme, index) => {
+            console.log(`  ${chalk.cyan(`[${index + 1}]`)} ${chalk.bold(theme.name)} - ${theme.description}`);
+            console.log(`      ${chalk.dim('See example:')} ${chalk.dim.underline(theme.example)}`);
+        });
+        console.log();
+        let themeChoice = await question(rl, chalk.cyan('? ') + `Enter 1-${THEMES.length} ` + chalk.dim('(1) '));
+        if (!themeChoice)
+            themeChoice = '1';
+        const themeIndex = parseInt(themeChoice, 10) - 1;
+        let theme = THEMES[0].id;
+        if (themeIndex >= 0 && themeIndex < THEMES.length) {
+            theme = THEMES[themeIndex].id;
+        }
+        else {
+            console.log(chalk.yellow('  Invalid choice, using SRCL'));
+        }
+        console.log(chalk.dim('\n  Optional fields (press Enter to skip)'));
+        const github = await question(rl, chalk.cyan('? ') + 'GitHub username? ' + chalk.dim('(optional) '));
+        const linkedin = await question(rl, chalk.cyan('? ') + 'LinkedIn username? ' + chalk.dim('(optional) '));
+        const twitter = await question(rl, chalk.cyan('? ') + 'Twitter username? ' + chalk.dim('(optional) '));
+        const website = await question(rl, chalk.cyan('? ') + 'Website URL? ' + chalk.dim('(optional) '));
+        rl.close();
+        const input = {
+            name,
+            title,
+            location,
+            email,
+            github: github || undefined,
+            linkedin: linkedin || undefined,
+            twitter: twitter || undefined,
+            website: website || undefined,
+            theme,
+        };
+        // Create folder structure
+        mkdirSync(folderName, { recursive: true });
+        mkdirSync(path.join(folderName, 'images'), { recursive: true });
+        const yamlPath = path.join(folderName, 'portfolio.yaml');
+        const yaml = generateYaml(input);
+        writeFileSync(yamlPath, yaml);
+        console.log();
+        console.log(chalk.green('✓') + ' Created ' + chalk.bold(folderName + '/'));
+        console.log();
+        console.log(chalk.dim('  Structure:'));
+        console.log(chalk.dim('  ├── ') + chalk.cyan('portfolio.yaml') + chalk.dim('  (your config)'));
+        console.log(chalk.dim('  ├── ') + chalk.cyan('images/') + chalk.dim('         (add images here)'));
+        console.log(chalk.dim('  └── ') + chalk.cyan('site/') + chalk.dim('           (generated after render)'));
+        console.log();
+        console.log(chalk.bold('Next steps:'));
+        console.log(chalk.dim('  1.') + ' Edit ' + chalk.cyan(`${folderName}/portfolio.yaml`) + ' and add your projects');
+        console.log(chalk.dim('  2.') + ' Add images to ' + chalk.cyan(`${folderName}/images/`));
+        console.log(chalk.dim('  3.') + ' Run: ' + chalk.cyan(`cd ${folderName} && devfolio render`));
+        console.log(chalk.dim('  4.') + ' Open: ' + chalk.cyan(`${folderName}/site/index.html`) + ' to view');
+        console.log();
+        console.log('Tip: Check ' + chalk.cyan('https://devfolio.page/portfolios/') + ' for examples');
+        console.log();
+    }
+    catch (err) {
+        rl.close();
+        throw err;
+    }
+}

package/dist/cli/commands/render.js

@@ -0,0 +1,105 @@
+import chalk from 'chalk';
+import path from 'path';
+import { existsSync } from 'fs';
+import { validatePortfolio, ValidationError, FileError, ParseError, } from '../helpers/validate.js';
+import { buildStaticSite } from '../../generator/builder.js';
+const TOTAL_STEPS = 4;
+function logStep(step, message) {
+    console.log(chalk.cyan(`[${step}/${TOTAL_STEPS}]`) + ' ' + message);
+}
+function findAvailableOutputDir(baseDir) {
+    const resolved = path.resolve(baseDir);
+    // If it doesn't exist, use it as-is
+    if (!existsSync(resolved)) {
+        return resolved;
+    }
+    // Find next available numbered directory
+    let counter = 1;
+    while (existsSync(`${resolved}${counter}`)) {
+        counter++;
+    }
+    return `${resolved}${counter}`;
+}
+export async function renderCommand(file, options) {
+    console.log();
+    try {
+        // Step 1: Validate
+        logStep(1, 'Validating portfolio...');
+        const portfolio = validatePortfolio(file);
+        console.log(chalk.green('    ✓') + ' Valid');
+        // Step 2: Load theme
+        const theme = options.theme || portfolio.theme || 'srcl';
+        logStep(2, `Loading theme: ${theme}`);
+        console.log(chalk.green('    ✓') + ' Theme loaded');
+        // Step 3: Generate HTML
+        const outputDir = findAvailableOutputDir(options.output);
+        logStep(3, 'Generating HTML...');
+        const result = await buildStaticSite(portfolio, {
+            outputDir,
+            theme,
+        });
+        console.log(chalk.green('    ✓') + ` Generated ${result.files.length} files`);
+        // Step 4: Done
+        logStep(4, 'Copying assets...');
+        console.log(chalk.green('    ✓') + ' Assets copied');
+        // Success output
+        console.log();
+        console.log(chalk.green('✓') + ' Portfolio rendered successfully!');
+        console.log();
+        console.log('  Output: ' + chalk.cyan(outputDir));
+        console.log('  Theme:  ' + chalk.cyan(theme));
+        console.log();
+        console.log(chalk.bold('Files created:'));
+        result.files.forEach((f) => {
+            console.log(chalk.dim('  •') + ` ${f}`);
+        });
+        console.log();
+        console.log(chalk.bold('Next steps:'));
+        console.log('  • Open ' + chalk.cyan(`${outputDir}/index.html`) + ' in your browser');
+        console.log('  • Or run ' + chalk.cyan(`npx serve ${outputDir}`) + ' for a local server');
+        console.log('  • Deploy the ' + chalk.cyan('site/') + ' folder to Vercel, Netlify, or GitHub Pages');
+        console.log();
+    }
+    catch (err) {
+        console.log();
+        if (err instanceof ValidationError) {
+            console.log(chalk.red('✗') + ' Validation failed\n');
+            for (const error of err.errors) {
+                console.log(`  ${chalk.red('•')} ${chalk.yellow(error.path)} - ${error.message}`);
+            }
+            if (err.errors[0]?.hint) {
+                console.log();
+                console.log(chalk.dim('  Expected format:'));
+                err.errors[0].hint.split('\n').forEach((line) => {
+                    console.log(chalk.dim(`    ${line}`));
+                });
+            }
+            console.log();
+            process.exit(1);
+        }
+        if (err instanceof FileError) {
+            console.log(chalk.red('✗') + ` ${err.message}`);
+            process.exit(1);
+        }
+        if (err instanceof ParseError) {
+            console.log(chalk.red('✗') + ' YAML syntax error');
+            if (err.line !== undefined) {
+                console.log(`  Line ${err.line + 1}: ${err.message}`);
+            }
+            else {
+                console.log(`  ${err.message}`);
+            }
+            console.log();
+            process.exit(1);
+        }
+        // Build errors
+        if (err instanceof Error) {
+            console.log(chalk.red('✗') + ' Build failed');
+            console.log();
+            console.log(`  ${err.message}`);
+            console.log();
+            process.exit(1);
+        }
+        throw err;
+    }
+}

package/dist/cli/commands/themes.js

@@ -0,0 +1,40 @@
+import chalk from 'chalk';
+const THEMES = [
+    {
+        id: 'srcl',
+        name: 'SRCL',
+        description: 'Terminal aesthetic with monospace fonts',
+        example: 'https://devfolio.page/portfolios/engineer-srcl/',
+    },
+    {
+        id: 'modern',
+        name: 'Modern',
+        description: 'Clean, contemporary design',
+        example: 'https://devfolio.page/portfolios/designer-modern/',
+    },
+    {
+        id: 'dark-academia',
+        name: 'Dark Academia',
+        description: 'Scholarly, vintage aesthetic',
+        example: 'https://devfolio.page/portfolios/researcher-academia/',
+    },
+];
+export function themesCommand() {
+    console.log();
+    console.log(chalk.bold('Available Themes'));
+    console.log();
+    THEMES.forEach((theme) => {
+        console.log(`  ${chalk.cyan(theme.id)}`);
+        console.log(`    ${theme.description}`);
+        console.log(`    ${chalk.dim('Example:')} ${chalk.dim.underline(theme.example)}`);
+        console.log();
+    });
+    console.log(chalk.dim('Usage:'));
+    console.log(`  devfolio render ${chalk.cyan('--theme srcl')}`);
+    console.log(`  devfolio render ${chalk.cyan('--theme modern')}`);
+    console.log(`  devfolio render ${chalk.cyan('--theme dark-academia')}`);
+    console.log();
+    console.log(chalk.dim('Or set the theme in your portfolio.yaml:'));
+    console.log(chalk.dim('  theme: srcl'));
+    console.log();
+}