1- # HackShelf 🚀
1+ # Badger Catalog 🚀
22
3- A beautiful, modern catalog of hacks and projects for the Badger 2350 device. Built with Astro, React, TypeScript, and Tailwind CSS.
4-
5- ![ HackShelf Preview] ( https://via.placeholder.com/800x400/6366f1/ffffff?text=HackShelf+Preview )
3+ A utilitarian catalog of hacks, apps, and documentation for the Badger 2350. Built with Astro, React, TypeScript, and Tailwind CSS for fast iteration and easy contributions.
64
75## ✨ Features
86
9- - ** 🎨 Beautiful UI** - Clean, modern design with dark/light mode support
10- - ** 📚 Comprehensive Catalog** - Browse hacks by difficulty, duration, and tags
11- - ** 📖 Detailed Tutorials** - Step-by-step guides with code snippets and copy functionality
12- - ** 🎯 Interactive Badge Diagram** - Explore Badger 2350 features with tooltips
13- - ** � Easy Navigation** - Intuitive layout with responsive design
14- - ** 📝 MDX Content** - Easy-to-edit content in Markdown with React components
15- - ** 🚀 Static Site** - Fast, SEO-friendly, deployable to GitHub Pages
16- - ** ♿ Accessible** - Built with accessibility best practices
7+ - ** 🎨 Purposeful UI** – Terminal-inspired dark theme with subtle neon accents
8+ - ** 📚 Comprehensive Catalog** – Browse hacks by difficulty, duration, and tags
9+ - ** 📖 Detailed Tutorials** – Step-by-step guides with runnable code snippets
10+ - ** 📝 MDX Content** – Markdown-first authoring with React components when needed
11+ - ** 🚀 Static Site** – Optimised for GitHub Pages or any static host
1712
18- ## � ️ Tech Stack
13+ ## 🛠 ️ Tech Stack
1914
20- - ** Framework** : [ Astro] ( https://astro.build/ ) - Static Site Generator
21- - ** Frontend ** : [ React] ( https://reactjs.org / ) + [ TypeScript] ( https://www.typescriptlang.org/ )
15+ - ** Framework** : [ Astro] ( https://astro.build/ )
16+ - ** UI ** : [ React] ( https://react.dev / ) + [ TypeScript] ( https://www.typescriptlang.org/ )
2217- ** Styling** : [ Tailwind CSS] ( https://tailwindcss.com/ )
23- - ** Components** : [ ShadCN UI] ( https://ui.shadcn.com/ )
24- - ** Icons** : [ Lucide React] ( https://lucide.dev/ )
25- - ** Content** : [ MDX] ( https://mdxjs.com/ ) with frontmatter
26- - ** Deployment** : GitHub Pages ready
18+ - ** Components** : [ shadcn/ui] ( https://ui.shadcn.com/ )
19+ - ** Icons** : [ Lucide] ( https://lucide.dev/ )
20+ - ** Content** : [ MDX] ( https://mdxjs.com/ )
2721
2822## 🚦 Quick Start
2923
3024### Prerequisites
3125
32- - Node.js 18+
26+ - Node.js 22+
3327- npm or yarn
3428
3529### Installation
3630
37311 . ** Clone the repository**
3832 ``` bash
39- git clone https://github.com/badger/hackshelf .git
40- cd hackshelf
33+ git clone https://github.com/badger/badger.github.io .git
34+ cd badger.github.io
4135 ```
42-
43362 . ** Install dependencies**
4437 ``` bash
4538 npm install
4639 ```
47-
48- 3 . ** Start development server**
40+ 3 . ** Start the development server**
4941 ``` bash
5042 npm run dev
5143 ```
52-
53- 4 . ** Open in browser**
44+ 4 . ** Open the app**
5445 ```
55- http://localhost:4321/hackshelf
46+ http://localhost:4321/
5647 ```
5748
5849### Available Scripts
5950
6051``` bash
6152npm run dev # Start development server
6253npm run build # Build for production
63- npm run preview # Preview production build
54+ npm run preview # Preview the production build
6455npm run astro # Run Astro CLI commands
6556```
6657
6758## 📁 Project Structure
6859
6960```
70- hackshelf /
61+ badger.github.io /
7162├── public/
7263│ ├── images/ # Static images and assets
7364│ └── favicon.svg
7465├── src/
7566│ ├── components/ # React components
76- │ │ ├── ui/ # ShadCN UI components
67+ │ │ ├── ui/ # shadcn/ui primitives
7768│ │ ├── hack-card.tsx
7869│ │ ├── navigation.tsx
7970│ │ └── ...
80- │ ├── content/ # MDX content files
81- │ │ └── hacks/ # Individual hack tutorials
82- │ ├── layouts/ # Astro layout components
83- │ ├── lib/ # Utility functions
84- │ ├── pages/ # Astro pages (routes)
85- │ └── styles/ # Global styles
86- ├── astro.config.mjs # Astro configuration
87- ├── tailwind.config.mjs # Tailwind CSS configuration
71+ │ ├── content/ # MDX content collections
72+ │ ├── layouts/ # Astro layouts
73+ │ ├── lib/ # Utilities
74+ │ ├── pages/ # Astro routes
75+ │ └── styles/ # Global styles
76+ ├── astro.config.mjs
77+ ├── tailwind.config.mjs
8878└── package.json
8979```
9080
9181## ✏️ Adding New Hacks
9282
93- ### 1. Create a new MDX file
83+ 1 . ** Create a new MDX file** in ` src/content/hacks/your-hack-name.mdx `
84+ 2 . ** Add assets** to ` public/images/hacks/ `
85+ 3 . ** Preview locally** with ` npm run dev `
9486
95- Create a new file in ` src/content/hacks/your-hack-name.mdx ` :
87+ Each MDX document supports frontmatter for metadata :
9688
9789``` mdx
9890---
9991title: "Your Hack Title"
10092description: "Brief description of what this hack does"
10193difficulty: "easy" # easy | medium | hard
102- duration: 30 # in minutes
103- tags: [ "LED", "WiFi", "Sensors"] # relevant tags
94+ duration: 30 # minutes
95+ tags: [ "LED", "WiFi", "Sensors"]
10496thumbnail: "/images/hacks/your-hack.jpg"
10597author: "Your Name"
10698date: "2025-01-15"
@@ -109,164 +101,52 @@ hardware:
109101 - "Additional components..."
110102github: "https://github.com/your-repo/hack-code "
111103---
112-
113- # Your Hack Title
114-
115- Write your tutorial content here using Markdown and MDX syntax...
116-
117- ## Step 1: Setup
118-
119- ``` python
120- # Your code examples
121- import badger2350
122- ```
123-
124- ## Step 2: Implementation
125-
126- More content...
127104```
128105
129- ### 2. Add images
130-
131- Place hack images in ` public/images/hacks/ ` and reference them in your MDX file.
132-
133- ### 3. Test locally
134-
135- Run ` npm run dev ` to see your new hack in the catalog.
136-
137- ## 🎨 Customizing the Design
106+ ## 🎨 Customising the Design
138107
139- ### Colors & Themes
140-
141- Edit ` tailwind.config.mjs ` and ` src/styles/globals.css ` to customize:
142-
143- - Color schemes
144- - Typography
145- - Component styles
146- - Dark/light mode variants
147-
148- ### Components
149-
150- All UI components are in ` src/components/ui/ ` using ShadCN UI. Customize or add new components as needed.
108+ - Update tokens in ` tailwind.config.mjs `
109+ - Extend typography and utilities in ` src/styles/globals.css `
110+ - Component overrides live in ` src/components/ui/ `
151111
152112## 🚀 Deployment
153113
154114### GitHub Pages
155115
156- 1 . ** Configure Astro for GitHub Pages**
157-
158- Update ` astro.config.mjs ` :
116+ 1 . Configure Astro:
159117 ``` js
160118 export default defineConfig ({
161- site: ' https://your-username .github.io' ,
162- base: ' /hackshelf ' ,
163- // ... other config
119+ site: ' https://badger .github.io' ,
120+ base: ' /' ,
121+ // ...
164122 })
165123 ```
166-
167- 2 . ** Build and deploy**
124+ 2 . Build the project:
168125 ``` bash
169126 npm run build
170127 ```
171-
172- 3 . ** Deploy to GitHub Pages**
173- - Push to your repository
174- - Enable GitHub Pages in repository settings
175- - Set source to GitHub Actions
176- - Site will be available at ` https://your-username.github.io/hackshelf `
177-
178- ### Other Platforms
179-
180- HackShelf can be deployed to any static hosting platform:
181- - Netlify
182- - Vercel
183- - Cloudflare Pages
184- - AWS S3 + CloudFront
128+ 3 . Push to ` main ` (GitHub Pages is already wired for this repo).
185129
186130## 🤝 Contributing
187131
188- We welcome contributions! Please see our [ Contributing Guide] ( src/pages/contribute.astro ) for details on:
189-
190- - Adding new hacks
191- - Improving existing content
192- - Bug fixes and features
193- - Code style guidelines
194-
195- ### Development Workflow
196-
197- 1 . Fork the repository
198- 2 . Create a feature branch: ` git checkout -b feature/amazing-hack `
199- 3 . Make your changes
200- 4 . Test locally: ` npm run dev `
201- 5 . Commit with descriptive messages
202- 6 . Push and create a Pull Request
203-
204- ## 📄 Content Guidelines
205-
206- ### Hack Tutorials Should Include:
207-
208- - ✅ Clear title and description
209- - ✅ Accurate difficulty and time estimates
210- - ✅ Complete component lists
211- - ✅ Step-by-step instructions
212- - ✅ Working code examples
213- - ✅ Troubleshooting tips
214- - ✅ Safety considerations
215- - ✅ Photos or diagrams
216-
217- ### Writing Style:
132+ 1 . Fork the repo: ` https://github.com/badger/badger.github.io/fork `
133+ 2 . Create a feature branch: ` git checkout -b feature/my-update `
134+ 3 . Make changes and run ` npm run build `
135+ 4 . Commit, push, and open a pull request
218136
219- - 📝 Use clear, beginner-friendly language
220- - 🔧 Explain technical concepts simply
221- - 🎯 Include practical tips and warnings
222- - 📸 Add visual aids when helpful
223- - 🔗 Link to relevant resources
137+ ### Community Links
224138
225- ## 📊 Analytics & SEO
139+ - 🐛 ** Issues ** : < https://github.com/badger/badger.github.io/issues >
226140
227- The site includes:
228- - Semantic HTML for accessibility
229- - Meta tags for social sharing
230- - Structured data for search engines
231- - Optimized images and assets
232- - Fast loading times
141+ ## 📄 License
233142
234- ## 🐛 Troubleshooting
143+ MIT License. See [ LICENSE ] ( LICENSE ) .
235144
236- ### Common Issues:
145+ ## 🙏 Acknowledgements
237146
238- ** Build fails with "Cannot find module" error**
239- - Run ` npm install ` to ensure all dependencies are installed
240- - Check that all imports use correct paths
241-
242- ** Images not displaying**
243- - Verify images are in ` public/images/ ` directory
244- - Check image paths start with ` /images/ `
245- - Ensure image formats are web-compatible (jpg, png, webp)
246-
247- ** Components not working**
248- - Ensure client-side components have ` client:load ` directive
249- - Check for TypeScript errors in the console
250-
251- ## � Support & Community
252-
253- - 🐛 ** Bug Reports** : [ GitHub Issues] ( https://github.com/badger/hackshelf/issues )
254- - 💡 ** Feature Requests** : [ GitHub Discussions] ( https://github.com/badger/hackshelf/discussions )
255- - 📚 ** Documentation** : [ Wiki] ( https://github.com/badger/hackshelf/wiki )
256- - 💬 ** Community** : [ Discord] ( https://discord.gg/badger-community )
257-
258- ## 📜 License
259-
260- This project is licensed under the MIT License - see the [ LICENSE] ( LICENSE ) file for details.
261-
262- ## 🙏 Acknowledgments
263-
264- - Built for the amazing Badger 2350 community
265- - Inspired by maker culture and open source collaboration
266- - Thanks to all contributors and hack creators!
147+ - Built for the Badger 2350 community
148+ - Powered by open source contributors and hardware experimenters everywhere
267149
268150---
269151
270- ** Happy Hacking!** 🎉
271-
272- Built with ❤️ for the Badger 2350 community
152+ ** Keep shipping badge hacks.**
0 commit comments