The website rebuild wishlist!

[Relequestual]

We are in the process of defining the requirements for a website rebuild.

Please share your "wish list" of things you would find on the ideal JSON Schema website.
These can be high or low level.

We have discussed and agreed some aspects already:

• All content (where possible) should be converted to markdown, and markdown should be the basis for site content
• The multiple repositories that power the site should merge content wise. The website should run from a single repository
• Style should be consistent. The new site should not identify the previous separate sites
• Layout and styling to be using Tailwind

Some things I have proposed but we haven't formally agreed:

• Built using react or vue, using next.js or nuxt.js framework
• Use TypeScript
• Deploy to Netlify*

Some things I assume we want. Let me know if you don't agree:

• Site wide search. Ability to target search to spec, docs, blog would be great. (Possible using https://docsearch.algolia.com)
• Site should be static generation. Implementations page should be data drive (based on JSON data)

There are currently three sites...
https://github.com/json-schema-org/json-schema-org.github.io
https://github.com/json-schema-org/understanding-json-schema
https://github.com/json-schema-org/blog

* I would have liked to be able to deploy to Cloudflare, as we manage our DNS and some other functions over there already. However, they only do deploy previews for PRs where the branch is not a fork. Previews for PRs which are from a fork is not supported. Cloudflare would have been a cheap option and allowed for multi-user access. Netlify is much more expensive, and per user pricing.
I THINK we could deploy live to Cloudflare, but have deploy previews done via Netlify. However, this would create potential disparity, especially considering the versions of node and python that might be required.

We do have some special considerations.
In the last 30 days we put out over 1TB of bandwidth.
Napkin calculations show we would put out over 200GB of bandwidth when you exclude the meta-schemas and specification files (which don't have analytics enabled). Free netlify would not be enough even if we proxy to cloudflare for the meta-schemas. We could
look at using Netlify's open source project offering, which is the pro plan, covering 400GB/month.

We have already asked the community if anyone wants to do the work (paid), and out of those who responded, we have selected @musemind. They seem to have the credability, and we have discussed ballpark pricing based on vague requirements.

We also have a sponsor for this work! The identity of the sponsor will be revealed later.

[jdesrosiers]

I really want this to stay as simple as possible. Heavy front-end frameworks make things more complicated, less accessible, and harder to maintain. The trade-offs might make sense if we're building a complex interactive application, but we're not. What we need is a mostly static site with maybe a few dynamic elements. There are plenty of lightweight libraries out there that would be able to support our modest dynamic front-end needs.

I'd like to see a super simple stack like Eleventy with basic CSS. Things like React, Vue, Sass, and TypeScript are all unnecessary complications. A lightweight css framework would be fine, but I strongly dislike Tailwind. I'd like to see a really simple minimal yet elegant design. Please, please, please no animations.

The most important considerations are that it's SEO friendly, accessible, and easy to maintain.

[Relequestual]

I was on the fence about this. I was concerned that we would limit our ability to add dynamic or more interesting components later on.
I did a little research on site that use 11ty.

I noticed it was used by eslint.
They are using a single page react application, so it's possible. (Their demo page)

My next concern was search. I Found many tools use https://docsearch.algolia.com, including eslint.
(It's free and seems easy to set up)

I concluded that 11ty would be the simplest and easiest to maintain.

In terms of Tailwind, using Postcss allows you to debulk the packaged result, meaning you only get the css you actually need. It's pretty smart. I strongly feel Tailwind will make it more maintainable. I for one don't want to be fighting CSS issues.
I want to give us the power to easily make layout and structural changes to specific pages without needing to touch css files.

[jviotti]

I was concerned that we would limit our ability to add dynamic or more interesting components later on.

You can still i.e. embed React or Vue in certain fragments of the app without making the entire thing powered by a SPA framework.

My next concern was search. I Found many tools use https://docsearch.algolia.com/, including eslint.

Do DocSearch require JavaScript? My impression is that indexing plain HTML should be a lot easier, and the search component can be embedded as mentioned above.

[Relequestual]

Right. The above comments were a record of me resolving my concerns about these things =]

[Relequestual]

@jdesrosiers Proof of concept work using next.js: #154 (comment)

Next.js is a static site generator, so you don't need all the heavy front end stuff. You output HTML and CSS as your build.

My feeling is, we (or maybe just I, if things are busy) should weigh this approach vs 11ty, and then pick key benefits for each, see which makes the most sense.

[karenetheridge]

In the last 30 days we put out over 1TB of bandwidth. Napkin calculations show we would put out over 200GB of bandwidth when you exclude the meta-schemas and specification files

That's a lot. Aside from the fact that the metaschemas really shouldn't be getting pulled down so much (it would be good to identify which implementations aren't caching these files and ask them to be better), these are static files that we could simply serve out of github with 307 redirects.

[Relequestual]

What's quite interesting is we took a huge dip on Thursday last week...
Unique users seems to remain steady though.

Graphs!

Google Analytics doesn't help because it can't track accessing the meta-schemas (unless we did horrible things).
We could pay $20 a month for Cloudflare Pro, which would include analytics. (With the free tier, we don't get enough information to tell where these requests are coming from.)
Might be a good move, meaning we could ditch Google Analytics.

Thoughts?

[jviotti]

Netlify offers a $15 analytics package too that is pretty handy.

[Relequestual]

Right, but we would also have to pay for hosting, and based on bandwidth requirements that would be expensive!

[flaksp]

Right, but we would also have to pay for hosting, and based on bandwidth requirements that would be expensive!

Is it possible to build Jamstack site (with Next.js Static HTML Export, for example) and host it on Cloudflare Pages? Its free plan is good enough, it offers unlimited bandwidth.

[Relequestual]

@flaksp right, and we're already doing that for our blog, using a worker based redirect =]

[musemind]

I made a little POC with NextJS (or "Jamstack" as @flaksp said).

• static build HTML output
• tailwindcss
• markdown, full customizable
• mixed markdown and custom components

https://github.com/camelstack/json-schema

It might sound overengineered to use a full stack framework, but look at the code:

I think it's almost as lean as pure static frameworks.
It checks all the other boxes from pure static frameworks, pages can be updated/created just with markdown.
But is capable of rich client stuff if needed with all the power of react. That would be a powerful basement for possible future expansions. The development experience is excellent.

[jdesrosiers]

First of all, @musemind, thank you for your efforts. I'm really excited for this site rebuild. Our site really needs it and I'm excited to work with you.

Second, everyone can mostly ignore my tech preferences. I believe that the developer should be the one who decides the best tools to fulfill the requirements of the stakeholders. As a non-developer stakeholder in this project, my job is to provide functional and non-functional requirements only. As someone with development background and a lot knowledge in the web in general, I might make some technical recommendations, but I expect @musemind to take it only as recommendation and I trust him to choose the best tool for the job.

Enough with the disclaimers, let's get to the point.

I did some basic performance checks on the PoC. At first I was very concerned, but then I ran my tests against a production build rather than the dev build and all my concerns went away. Pages loaded quickly, were small enough, and responded with HTML. With this approach there must be a Markdown parser as part of the JavaScript in the browser. I was afraid that the Markdown parser would be very large or slow, but neither appear to be a problem. So far, I have no reason to complain, but I've seen how even simple React sites can get out of hand quickly, so I'm curious how this PoC will scale. (See our blog site for an example of a simple React site with terrible performance.)

It's significantly more complicated and heavy than a static site generator, but most of the complicated bits are just a one-time setup cost and then we'll just end up working in Markdown for most things. So, I'm not too worried about usability as long as we can set things up nicely.

Question: What flavor of Markdown does the PoC use? Do we have options?

[Relequestual]

It's unclear what flavour of markdown the library in the PoC uses.
Having spent 2 minutes googling... If we used remark (https://github.com/remarkjs/react-markdown) it has plugins, so we could for example use GitHub flavoured Markdown.
so, we have options.

[musemind]

Thanks for your feedback! Im not really familiar with markdown flavors yet. I used the first markdown parser that looked suitable. We have the whole npm ecosystem to choose our parser from, so I'm pretty sure that won't be a problem. What flavor suits our need and why? I can adapt the POC if you can provide an example of specific GitHub flavored markdown.

Performance: NextJS is know for their focus on performance and capabilities for 100 points Lighthouse scores. I'll keep the importance of speed and SEO with in mind.

Aside the stack: Are there already ideas / wireframes for the concept of the page? I think it's important to think that through as well. We can use a shared figma page for some prototyping. That's always worth the effort and will align everyones ideas/expectations.

[jdesrosiers]

What flavor suits our need and why?

I don't care too much about which Markdown flavor is used, but CommonMark or Github Flavored Markdown is best because it's the most widely adopted and what people are most familiar with. Two features I know we're going to want that don't come with all flavors are footnotes and syntax highlighting in code blocks.

Are there already ideas / wireframes for the concept of the page?

No, we we need your guidance on design matters.

[Relequestual]

Are there already ideas / wireframes for the concept of the page?
No, we we need your guidance on design matters.

Accurate! 100%

What flavor suits our need and why?

Let's leave it as what you've found for now, and we can swap it if we run into problems with the content.

Thanks again for your work on this @musemind

[Relequestual]

See our blog site for an example of a simple React site with terrible performance.

@jdesrosiers as an aside, we could probably run the blog in static mode, removing the need for the JS client side.
A lighthouse report does say some of the images could be better optimised, which is true, but I thought the site was pretty speedy personally.

[jdesrosiers]

The lighthouse performance score for one of our blog posts on mobile is 29!

A blog post is 3.7MB!!! If you disable javascript, it's only 762KB and the user experience is almost identical.

[Relequestual]

Yikes! OK! It's clear in my mind we need to switch the blog site into static mode!

[Relequestual]

Hey @musemind, what's the latest? Are you still up for doing this work? =]

[musemind]

@Relequestual Pretty busy these days, otherwise no news.

Yes, I would still like to implement it. Is there a go from a financial point of view?

[Relequestual]

Yes. Sorry I thought that was communicated.
If you're feeling like you're able to commit to the work, just let me know, and we can see if anyone else wants to take on the contract.
Thanks =]

[musemind]

I’ll take over the project, I had only thought the agreement with the investor was not yet final.

[musemind]

I made good experience with the quality of algolia search for as-you-type text fuzzy search results.

They offer a free tier for open source project in exchange of a small algolia logo on the search results.
https://www.algolia.com/for-open-source/

Is this an option for us?

[Relequestual]

It's used by many top tier open source projects. I'm OK with this.

[musemind]

Hi together,

Stage for the new JSON schema website: 🥳
https://json.camelstack.com/

I am curious about your feedback.

Regards,
Johannes

[jdesrosiers]

Looking good! This is a huge improvement. Here are some things I noticed.

1. Several links aren't going to the right place on the home page. Specifically, Slack and Office Hours
2. The links to the specification and implementation pages seem quite buried at the bottom of the home page. These are important resources and I think they should be presented prominently such as in the top menu or in one of those big button-like callouts like getting started, slack, and discussions.
3. I like the search feature! That could be useful.
4. Almost all of the links are broken on the specifications page.
5. Link behavior is odd. For example: When I click the implementations link at the bottom of the home page, I don't go to the top of the implementations page, I end up scrolled part way down the page.
6. The table view for the validators on the implementations page is a nice improvement. I'd like to see similar styling for the other categories as well.
7. On this blog, the banner image overflows horizontally. This seem to be the only one that has this responsiveness problem.
8. I don't see the same nice syntax highlighting for schemas on mobile as I do on desktop.
9. Schema code blocks (which look really nice) have a different look and feel from other code blocks such as YAML. Can we make these have the same color scheme?
10. Nice job porting over all the Understanding JSON Schema content. I bet that was tedious work, but it's greatly appreciated. The schema component looks great.
11. The draft-specific boxes aren't always styled the same. I prefer the yellow.
12. The note boxes are styled as normal blockquotes. I don't think that makes sense. I'd like to see those styled to make it more clear that they're an aside of some sort. Maybe something similar to the yellow draft-specific boxes.
13. When browsing the docs section on mobile, the contents don't show on the left side which makes navigation much less intuitive. I think it would help to add some next links to the bottom of each page.

[musemind]

Thanks for the detailed feedback! I'll fix the issues next week.