Skip to content

New Site Design Astro Migration & Modernization (V2)#38

Open
shadstoneofficial wants to merge 12 commits into
handshake-org:gh-pagesfrom
shadstoneofficial:gh-pages
Open

New Site Design Astro Migration & Modernization (V2)#38
shadstoneofficial wants to merge 12 commits into
handshake-org:gh-pagesfrom
shadstoneofficial:gh-pages

Conversation

@shadstoneofficial

@shadstoneofficial shadstoneofficial commented May 15, 2026

Copy link
Copy Markdown

Overview

This Pull Request represents a comprehensive migration of the Handshake website from raw HTML/CSS to a modern Astro (v4) architecture with Tailwind CSS.

The goal of this migration is to significantly improve the developer experience, make the site easier for the community to maintain, enhance SEO, and modernize the visual aesthetic to reflect Handshake's role as serious, decentralized infrastructure (shifting away from the heavy "crypto/blockchain" purple aesthetics to a clean, professional monochromatic grey/black theme).

🔗 Live Preview

https://handshakenew.skyinclude.com

Key Architectural Changes

  1. Astro Framework: Migrated all raw .html files into modular .astro pages and components (Layout.astro, Header.astro, Footer.astro). This prevents code duplication (like having to update the header 20 times).
  2. Tailwind CSS: Replaced the fragmented custom CSS files with Tailwind utility classes for a highly responsive, modern, and easily maintainable styling system.
  3. Legacy Preservation: The original legacy/ directory is kept intact in the repository to ensure no historical data is lost.
  4. Content Migration: Extracted all the historical content (Grant Sponsors, Claim instructions, FAQs, Notices) and wrapped them using @tailwindcss/typography to ensure they render beautifully in the new layout.
  5. Interactive Hero: Added a custom three.js interactive "interconnected network" background to the homepage hero to visually represent the peer-to-peer network.

Feature Additions & Fixes

  • SEO & Sitemap: Installed @astrojs/sitemap to auto-generate sitemap-index.xml. Added custom meta descriptions to all primary pages.
  • AI Agent Context: Created /skill.md and /llms.txt endpoints configured to return text/plain so AI agents can natively read Handshake rules and login instructions via headless SSO.
  • Historical Accuracy: Updated the Grant Sponsors and Claim pages to clearly reflect that these events occurred in the past (2020) and are no longer active following the soft fork.
  • Native Redirects: Converted legacy HTML redirects (/discord, /telegram) into native server-side redirects via astro.config.mjs.
  • Custom 404: Replaced the default Astro 404 page with a custom, branded Handshake 404 error page.
  • Bob Wallet: Updated all references from .io to .org.

Testing Instructions for Reviewers

  1. Clone this branch locally.
  2. Run npm install
  3. Run npm run dev
  4. Verify the interactive hero background on http://localhost:4321.
  5. Verify the routing to /faq, /grant-sponsors, /community, and /notice.

Deployment

This project includes a .github/workflows/deploy.yml configured to use the official withastro/action. Upon merging to master, the Astro site will build and push statically to the GitHub Pages branch.

@taylormartens

Copy link
Copy Markdown

Tailwind isn’t a design system. Right now this just looks like generic output, no visual identity, no UX personality. Hard pass on the aesthetic. Pr for updates I’d be open to but not with this “redesign” attached.

@NamerTips

Copy link
Copy Markdown

This proposal leans more into a code update than a formal modernization of the Handshake.org site itself. Essentially, what's being proposed in the moment is better than what currently exists. Therefore, implementing this proposal could act as a signal the Handshake protocol and community are alive and well.

However, the proposal doesn't necessarily carry a long-term aesthetic. The vibe-coded feel could hurt the site's sense of authority in the long-run - so it would need to be updated eventually. It would also be nice to add additional features to the site that accentuate Handshake's capabilities and community contributions.

@taylormartens

Copy link
Copy Markdown

I already said in my previous comment I was open to updated information. Your comment back neglects to point that out.

You stated yourself the “vibe coded feel” could hurt the site’s authority long term. That alone makes attaching this redesign direction basically DOA.

Modernization, redesign, and updated information are three different conversations that have no place being bundled together in a one shot all in one update.

@NamerTips

Copy link
Copy Markdown

@taylormartens The posted comment wasn't in response to you. It was for @shadstoneofficial.

While on the subject of your response though, "Modernization, redesign, and updated information" are indeed three different branches of consideration. This is coming from someone with extended experience with each.

This proposal may not be comprehensive - but it's definitely timely considering where things are in the age of vibe-coding. As originally stated, the proposal doesn't necessarily carry a long-term aesthetic - but it would make the Handshake.org site current. Not captivating or competitive. Just current.

In due time, there will be a need for more robust UI, UX and information updates. Considering the state of the protocol and community sentiment at the moment, those robust changes can't be a top priority where consensus is scattered.

@HellotoSinaa

Copy link
Copy Markdown

Its time to change

@HellotoSinaa

Copy link
Copy Markdown

https://handshakenew.skyinclude.com/files/handshake.txt
Its better to make high class .pdf for our ↳Whitepaper . it seems very simple but Handshake has own big world !

@realrasengan

Copy link
Copy Markdown

Personally, I think that page [1] looks amazing.

[1] https://handshakenew.skyinclude.com

@shadstoneofficial

Copy link
Copy Markdown
Author

Added the requested whitepaper/design notes update across the site.

Changes included

Updated locations

  • homepage resource links
  • footer
  • sitemap page
  • how-it-works page
  • grant-sponsors page

Also verified

  • the new PDF is available at /files/handshake.pdf
  • the existing text version remains at /files/handshake.txt
  • Astro build passes successfully

Build cleanup

  • Replaced external redirect config for /discord and /telegram with dedicated redirect pages
  • Lazy-loaded the homepage Three.js background to improve bundle splitting

One non-blocking Vite warning remains because the Three.js chunk is still larger than the default warning threshold, but this does not affect functionality or deployment.

@HellotoSinaa

Copy link
Copy Markdown

I have some ideas can improve and update handshake's whitepaper this is first idea to add for example ' https://dx.doi.org/10.2139/ssrn.6757159 ' "its Punycode and Unicode" another will add soon...

@HellotoSinaa

Copy link
Copy Markdown

Added the requested whitepaper/design notes update across the site.

Changes included

Updated locations

  • homepage resource links
  • footer
  • sitemap page
  • how-it-works page
  • grant-sponsors page

Also verified

  • the new PDF is available at /files/handshake.pdf
  • the existing text version remains at /files/handshake.txt
  • Astro build passes successfully

Build cleanup

  • Replaced external redirect config for /discord and /telegram with dedicated redirect pages
  • Lazy-loaded the homepage Three.js background to improve bundle splitting

One non-blocking Vite warning remains because the Three.js chunk is still larger than the default warning threshold, but this does not affect functionality or deployment.

page 5 has problem could you please resolve it, thank you

@marioo-lab

Copy link
Copy Markdown

Respect for the initiative and the effort! 👏

I liked the minimalistic design of the old page better, and I think we should stick with it if possible. But I also salute the updates. I would agree with a mixed version keeping original design and only updating the content.

@HellotoSinaa

Copy link
Copy Markdown

This is an open source protocol. I think it needs to be updated every day, even if it's just 1%.

@HellotoSinaa

Copy link
Copy Markdown

How can we upgrade Handshake whitepaper??

@shadstoneofficial

Copy link
Copy Markdown
Author

@HellotoSinaa that is a big question to update a whitepaper....

I have been thinking about this PR for a while and I am not going to ruffle feathers trying to update this website.

if you'd like I can make an account for you on https://learnhns.com as a community contributor there and you can make posts

for an updated whitepaper, maybe you could make your own version updated and can cite it. but to change a whitepaper in my opinion is a big ask.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants