Modernize EIPs Platform: Migration from Jekyll

[SeanLuis]

Current Implementation Issues

• Jekyll static site generator is showing its age
• Slow build times affecting contributor workflow
• Limited search capabilities (basic GitHub search)
• Complex setup for local development
• No hot reload for content changes
• Limited component reusability
• Technical debt in custom plugins/extensions

Proposed Solution

Migration to Nuxt 3

Demo

https://eips-ethereum.netlify.app/

Video

Demo.mp4

Tech Stack

• Nuxt 3
• TailwindCSS
• Algolia Search or (own search)

Advantages

Developer Experience

• Hot module replacement
• TypeScript support out of the box
• Better debugging tools
• Simplified local setup

Performance

• Faster build times
• Better code splitting
• Improved SEO through static generation
• Enhanced caching strategies

Content Management

• Native markdown support
• Better content querying
• Built-in draft system
• Improved frontmatter handling

Implementation Timeline

• Core setup & content migration
• Feature parity & testing
• Deployment

Migration Strategy

• Create parallel development environment
• Implement core features with Nuxt
• Migrate existing content
• Community testing phase
• Progressive rollout

Risks

• Learning curve for current maintainers
• Potential URL structure changes
• Migration of custom Jekyll plugins
• Temporary maintenance of dual systems

@fjl @Shadowfiend @pelle @jm3

[SamWilsn]

I've been working on a rework of the EIPs/ERCs build system for quite some time now. You can follow my progress over at https://github.com/eips-wg/

Repositories of note:

• https://github.com/eips-wg/EIPs
• https://github.com/eips-wg/ERCs
• https://github.com/eips-wg/preprocessor

[SeanLuis]

I've been working on a rework of the EIPs/ERCs build system for quite some time now. You can follow my progress over at https://github.com/eips-wg/

Repositories of note:

• https://github.com/eips-wg/EIPs
• https://github.com/eips-wg/ERCs
• https://github.com/eips-wg/preprocessor

I understand you've been working on restructuring the EIPs/ERCs build system with a multi-repository approach using Zola. The complexity of this structure raises several concerns:

• Fragmentation: Multiple repositories (eips-wg-*, preprocessor, registry, etc.) create unnecessary maintenance overhead
• Custom preprocessing: Required transformation between EIP markup and Zola seems inefficient
• Poor documentation: The approach lacks comprehensive documentation, making it difficult for new contributors to understand the system
• Increased complexity: Multiple interconnected repositories increase the learning curve and potential points of failure

The proposed Nuxt 3 migration offers significant advantages:

• Consolidated solution: Single repository architecture
• Native markdown support: No preprocessing required
• Modern developer experience: Hot module replacement, TypeScript support
• Simplified workflow: Faster builds and local development
• Established ecosystem: Better documentation and community support

Is there a specific technical requirement that necessitates this multi-repository Zola approach over a more streamlined solution?

[SamWilsn]

• Fragmentation: Multiple repositories (eips-wg-*, preprocessor, registry, etc.) create unnecessary maintenance overhead

There will be three in the current iteration: EIPs, ERCs, and build-eips (renamed from preprocessor). The eip-wg-* repositories are leftovers from when we were planning to further split the repositories. registry is from an attempt at a number assignment bot that's on hold for now.

Custom preprocessing: Required transformation between EIP markup and Zola seems inefficient

Inefficient in the sense of performance? The build takes about a minute, and most of that is unoptimized git operations. Inefficient in having to maintain the code? I have no argument against that.

• Poor documentation: The approach lacks comprehensive documentation, making it difficult for new contributors to understand the system

True, but the project isn't complete yet.

Increased complexity: Multiple interconnected repositories increase the learning curve and potential points of failure

I mean... Nuxt, vue, and vite aren't exactly complexity-free either.

• Consolidated solution: Single repository architecture

We don't want a single repository. We want at least two (EIPs and ERCs).

Native markdown support: No preprocessing required

True, but by doing preprocessing, we can statically generate more things. So far we render csl-json into proper citations and eventually we'll probably replace MathJax.

• Modern developer experience: Hot module replacement, TypeScript support

I don't see this as a benefit.

• Simplified workflow: Faster builds and local development

First, you'd need to back this up with some data. Second, build speed isn't everything.

• Established ecosystem: Better documentation and community support

True, but two of the EIP Editors are Rust developers and zero are TypeScript developers.

Is there a specific technical requirement that necessitates this multi-repository Zola approach over a more streamlined solution?

Nothing requires Zola, no. We do have the requirement of separate ERC and EIP repositories, so putting common build stuff into a third repository makes some sense.

[SamWilsn]

Rereading my response, it might sound like I'm completely opposed to using the work you've done. I'm not! I wouldn't mind seeing your source if you have it up somewhere.

---

From a very unscientific look at the transferred size of your demo vs. eips-wg:

Where	Nuxt	eips-wg
index	1.86MB	0.264MB
EIP-712	416.88kB	503.41kB
EIP-7600	146.23kB	247.95kB

Obviously our sites have different features, so this isn't an apples to apples comparison.

---

Some minor bugs I've found using your demo:

• The search doesn't search by proposal number.

  

• Direct linking to proposals 404s.

  

• Solidity has no syntax highlighting.

  

• Math is not typeset.

  

• /LICENSE link doesn't go to the license.

[SeanLuis]

Thank you for taking the time to review my demo and provide detailed feedback. I appreciate your insights and would like to address some of the points you raised.

Regarding the Demo's Current State

First, I want to clarify that this demo was developed in less than 3 days as a proof of concept to demonstrate what's possible with Nuxt 3. It's not a finished product but rather a starting point for discussion about potential modernization paths.

On Repository Structure

While your plan to consolidate from many repos to three (EIPs, ERCs, and build-eips) is definitely better than the current state, I wonder if we're solving the right problem. Having build tools in a separate repo often creates synchronization headaches - developers need to update multiple repos for many changes.

I understand your requirement for separate EIPs and ERCs repositories. Nuxt can certainly accommodate this approach while still providing unified build tooling.

Regarding Preprocessing

Fair point about the build time - a minute isn't terrible. My concern is more about maintainability. Custom preprocessing creates a knowledge barrier for new contributors who have to understand both the EIP format and how the preprocessing transforms it. This doubles the learning curve.

While you make a good point about static generation capabilities, Nuxt also supports custom build plugins that could handle citation rendering and MathJax replacement.

On Technology Choices

"Nuxt, vue, and vite aren't exactly complexity-free either."

You're absolutely right! However, they're widely documented complexities with established patterns. When contributors hit a wall with Nuxt, they have thousands of Stack Overflow answers and tutorials to reference. With custom preprocessing, they're dependent on the team.

Regarding Repository Requirements

The EIPs/ERCs separation makes sense. Nuxt can actually work well with this structure - we could have a shared Nuxt module package that both repos import, giving you the separation with unified tooling.

On Developer Experience

"I don't see this as a benefit."

This surprised me! Hot module replacement saves enormous time during content editing. Have you tried working in an environment with it? It's one of those things that doesn't seem important until you've experienced it.

While you may not personally see TypeScript and hot module replacement as benefits, they do reduce the barrier to entry for many potential contributors. That said, I understand your point about the current editor team's expertise in Rust.

Performance Considerations

I'd be happy to provide more detailed performance benchmarks. The initial page load size can be further optimized - what you're seeing is an unoptimized build with development features enabled.

Bugs Identified

Thank you for pointing out these issues:

• Search by proposal number
• Direct linking 404s
• Solidity syntax highlighting
• Math typesetting
• License link

These are all fixable items that would be addressed in a complete implementation.

On the Rust vs. TypeScript Point

This is possibly the most compelling argument you've made. Tools should match the team's expertise. Though I'd suggest that expanding beyond the current editors' comfort zone might encourage more diverse contribution.

Moving Forward

What if we considered a hybrid approach? Use Rust for the heavy lifting (data processing) but Nuxt for the presentation layer?

I'm open to collaboration or even a hybrid approach that leverages the strengths of both solutions. I believe we share the same goal of improving the EIPs platform, even if we have different approaches to getting there.

Would you be interested in discussing specific requirements in more detail?

[JoshDavisLight]

As someone that uses the EIP website often, @SeanLuis demo is a breath of fresh air and brings some needed functionality to the site, as well as an aesthetic redesign that makes parsing EIPs more pleasing.

[SeanLuis]

As someone that uses the EIP website often, @SeanLuis demo is a breath of fresh air and brings some needed functionality to the site, as well as an aesthetic redesign that makes parsing EIPs more pleasing.

@JoshDavisLight thanks for the feedback!