Skip to content

Commit 18195fa

Browse files
fernandotonacoderfernandotonacoder
committed
update readme and docs
1 parent f9797ca commit 18195fa

4 files changed

Lines changed: 202 additions & 774 deletions

File tree

‎README.md‎

Lines changed: 16 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
# Fernando Tona - Portfolio Website
1+
# Fernando Tona - Professional Profile
22

33
[![CI/CD Pipeline](https://github.com/fernandotonacoder/fernandotonacoder.github.io/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/fernandotonacoder/fernandotonacoder.github.io/actions/workflows/ci-cd.yml)
44
[![GitHub Pages](https://img.shields.io/badge/GitHub%20Pages-deployed-success?logo=github)](https://fernandotonacoder.github.io)
@@ -11,7 +11,7 @@
1111
![CSS3](https://img.shields.io/badge/CSS3-1572B6?logo=css3&logoColor=white)
1212
![JavaScript](https://img.shields.io/badge/JavaScript-F7DF1E?logo=javascript&logoColor=black)
1313

14-
> Personal portfolio website showcasing my work as a Software Developer specializing in .NET/C# and Azure.
14+
> Professional profile website showcasing my expertise as a Software Developer.
1515
1616
**Live Site:** [fernandotonacoder.github.io](https://fernandotonacoder.github.io)
1717

@@ -39,7 +39,7 @@
3939
Simply visit: **[fernandotonacoder.github.io](https://fernandotonacoder.github.io)**
4040

4141
### For Developers
42-
\`\`\`bash
42+
```bash
4343
# Clone and install
4444
git clone https://github.com/fernandotonacoder/fernandotonacoder.github.io.git
4545
cd fernandotonacoder.github.io
@@ -55,11 +55,11 @@ open src/index.html
5555

5656
# Or Option 2: with local server
5757
python -m http.server 8000 -d src
58-
\`\`\`
58+
```
5959

6060
## Project Structure
6161

62-
\`\`\`
62+
```
6363
src/
6464
├── index.html # Main page
6565
├── css/style.css # Styles
@@ -68,17 +68,17 @@ src/
6868
│ ├── custom-select.js # Language selector
6969
│ └── *.test.js # Unit tests
7070
└── locales/ # Translation files (en, es, fr, pt)
71-
\`\`\`
71+
```
7272

7373
## Development Commands
7474

75-
\`\`\`bash
76-
npm test # Run tests
77-
npm run lint # Check code quality
78-
npm run lint:fix # Auto-fix issues
79-
npm run format # Format code
80-
npm run format:check # Check formatting
81-
\`\`\`
75+
```bash
76+
npm test # Run tests with Jest
77+
npm run lint # Check code quality with ESLint
78+
npm run lint:fix # Auto-fix issues with ESLint
79+
npm run format # Format code with Prettier
80+
npm run format:check # Check formatting with Prettier
81+
```
8282

8383
## CI/CD Pipeline
8484

@@ -89,17 +89,12 @@ npm run format:check # Check formatting
8989
## Author
9090

9191
**Fernando Tona**
92-
[Website](https://fernandotonacoder.github.io) • [LinkedIn](https://www.linkedin.com/in/fernandotona/) • [GitHub](https://github.com/fernandotonacoder)
92+
[Website](https://fernandotonacoder.github.io) • [LinkedIn](https://www.linkedin.com/in/fernandotona/) • [GitHub](https://github.com/fernandotonacoder) • fernandotonacoder@protonmail.com
9393

9494
## Documentation
9595

96-
- **[Technical Documentation](docs/project-instructions.md)** - Architecture, conventions, and detailed guides
97-
- **[Development Guide](docs/development.md)** - Setup, testing, and contribution guidelines
98-
- **[Design System](docs/design.md)** - Colors, typography, and styling patterns
99-
100-
## License
101-
102-
MIT License - see [LICENSE](LICENSE) for details.
96+
- **[Technical Documentation](docs/project-instructions.md)** - Architecture and system internals
97+
- **[Contributing Guide](docs/CONTRIBUTING.md)** - Development workflow and key decisions
10398

10499
---
105100

‎docs/CONTRIBUTING.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Contributing Guide
2+
3+
## Development Setup
4+
5+
```bash
6+
git clone https://github.com/fernandotonacoder/fernandotonacoder.github.io.git
7+
cd fernandotonacoder.github.io
8+
npm install
9+
```
10+
11+
**Local development:** Open `src/index.html` in browser or use `python -m http.server 8000 -d src`
12+
13+
---
14+
15+
## Workflow
16+
17+
**Branch protection is enabled.** Always work on feature branches:
18+
19+
```bash
20+
git checkout -b feature/your-feature
21+
# make changes
22+
git add .
23+
git commit -m "Description"
24+
git push origin feature/your-feature
25+
# Create PR on GitHub
26+
```
27+
28+
**CI/CD Pipeline:**
29+
- **On PR:** Tests, linting, format checks
30+
- **On merge to main:** Auto-deploys to GitHub Pages
31+
32+
---
33+
34+
## Commands
35+
36+
```bash
37+
npm test # Run Jest tests
38+
npm run lint # ESLint check
39+
npm run lint:fix # Auto-fix linting issues
40+
npm run format # Prettier format all files
41+
npm run format:check # Check if formatted correctly
42+
```
43+
44+
---
45+
46+
## Architecture Decisions
47+
48+
### Translation System
49+
50+
**Why custom instead of i18n library?**
51+
- No external dependencies
52+
- Tiny footprint (~100 lines)
53+
- Does exactly what we need, nothing more
54+
55+
**Language detection priority:**
56+
1. localStorage (`language` key)
57+
2. Browser language (`navigator.language`)
58+
3. Fallback to English
59+
60+
**Translation keys:** Flat structure in `/locales/*.json`. HTML elements use `data-translate` attributes:
61+
- `data-translate="key"` → Updates `textContent`
62+
- `data-translate-alt="key"` → Updates `alt` attribute
63+
- `data-translate-html="key"` → Updates `innerHTML` (supported but unused)
64+
65+
**SEO:** Dynamically updates `<title>`, `<meta name="description">`, and Open Graph tags on language change.
66+
67+
### Custom Language Selector
68+
69+
**Why not a normal `<select>`?**
70+
- Needed custom styling (glassmorphism effect)
71+
- Better control over appearance
72+
- Still accessible with keyboard navigation
73+
74+
### CSS Architecture
75+
76+
**Color scheme:** CSS variables in `:root` for easy theming
77+
78+
**Icon colors:** SVG filters for color manipulation:
79+
```css
80+
/* White icons on dark background */
81+
filter: brightness(0) invert(1);
82+
83+
/* Dark icons on light background */
84+
filter: brightness(0) invert(0);
85+
```
86+
87+
**Glassmorphism effect:**
88+
```css
89+
background: rgba(255, 255, 255, 0.1);
90+
backdrop-filter: blur(10px);
91+
```
92+
93+
### ESLint Config
94+
95+
**Why flat config (`eslint.config.mjs`)?**
96+
- ESLint 9+ requires it
97+
- Different environments need different globals:
98+
- Browser JS: `setLanguage`, `getCurrentLanguage` (custom globals)
99+
- Test files: Jest globals (`describe`, `test`, `expect`)
100+
- Jest config: Node.js globals (`module`)
101+
102+
### Prettier Config
103+
104+
**Why these settings?**
105+
- Double quotes, no trailing commas, always parens → Personal preference from TypeScript/C# background
106+
- `tabWidth: 4` → Personal preference from C# background
107+
108+
---
109+
110+
## Adding Features
111+
112+
### New Translation
113+
114+
1. Add key to **ALL** locale files (`en.json`, `es.json`, `fr.json`, `pt.json`)
115+
2. Add `data-translate="yourKey"` to HTML element
116+
3. Test in all languages
117+
118+
### New Language
119+
120+
1. Create `/locales/{lang}.json` with all existing keys
121+
2. Update `supportedLangs` in `js/translations.js`
122+
3. Update `languageNames` in `js/custom-select.js`
123+
4. Add option to language selector in `index.html`
124+
5. Write tests
125+
126+
---
127+
128+
## Gotchas
129+
130+
**Tests failing?**
131+
- Make sure JSON files don't have trailing commas (Prettier removes them automatically)
132+
- Run `npm test -- --clearCache` if weird caching issues
133+
134+
**Translations not loading?**
135+
- Check browser console for fetch errors
136+
- Verify JSON is valid
137+
- Check file paths are correct
138+
139+
**Styles not applying?**
140+
- Hard refresh: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
141+
142+
**Can't push to main?**
143+
- That's intentional. Create a feature branch and PR.
144+
145+
---
146+
147+
## Testing Strategy
148+
149+
**What we test:**
150+
- Translation system: Loading, language switching, localStorage persistence
151+
- Custom selector: UI interactions, language selection
152+
153+
**What we don't test:**
154+
- Bootstrap components (already tested by Bootstrap)
155+
- Browser APIs (fetch, localStorage)
156+
- CSS styling
157+
158+
**Coverage target:** No specific target, just test critical logic.
159+
160+
---
161+
162+
## Design Tokens
163+
164+
### Colors
165+
```css
166+
--clr-navy: #001f3f; /* Primary background */
167+
--clr-blue-text: #2563eb; /* Accent text */
168+
--clr-linkedin: #0077b5;
169+
--clr-github: #333;
170+
```
171+
172+
### Spacing Scale (Bootstrap)
173+
`0` = 0, `1` = 4px, `2` = 8px, `3` = 16px, `4` = 24px, `5` = 48px
174+
175+
### Breakpoints
176+
- Mobile first approach
177+
- Key breakpoint: 992px (tablets → desktop)
178+
179+
---
180+
181+
## Resources
182+
183+
- [Jest Docs](https://jestjs.io/docs/getting-started)
184+
- [ESLint Flat Config](https://eslint.org/docs/latest/use/configure/configuration-files)
185+
- [Bootstrap 5](https://getbootstrap.com/docs/5.3/)
186+
- [CSS Filter Generator](https://codepen.io/sosuke/pen/Pjoqqp) for SVG colors

0 commit comments

Comments
 (0)