fastify / website Goto Github PK

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

Hi, I believe the GitHub Pages settings need to be changed to serve from a custom subdomain. A possible option is something like fastify-website-next.github.io. It also needs to select the gh-pages branch. Here's the interface I see on a personal repo, but it's possible it could be different for organisation repos.

We must support all the old website links from https://fastify.io/

After merging #44 it seems that:

• https://www.fastify.io/docs/latest/ works as expected
• https://www.fastify.io/docs/master/ is being redirected to latest. We may thing if we want the canary link as docusaurus does: https://docusaurus.io/docs/next. I think the support the redirect from /master is good, I would drop this wording as fastify did in its main branch
• https://www.fastify.io/docs/v4.11.x/ supported
• https://www.fastify.io/docs/v3.4.x/ et similar, should be redirected to v3.29.x
• https://www.fastify.io/docs/v2.9.x/ et similar, should be redirected to v2.15.x
• https://www.fastify.io/docs/v1.3.x/ et similar, should be redirected to v1.14.x
• Other page links

💡 An interesting thing to implement: AFAIK Docusaurus does not support one documentation version with multiple labels (eg: create one /versioned_docs/v2.x that creates the routes /v2.15.x, /2.14.x etc...). It would be awesome to build a plugin that does this trick

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

Following on from fastify/fastify#3492, I think we have everything we need to import documentation into this project.

For v3 (current):

• The /docs/ folder from main branch needs to be cloned into /docs/ locally.
• While we restructure these docs, we should use docs-reorg branch instead (but can easily switch main once it is merged).

For v2:

• The /docs/ folder from 2.x branch needs to be cloned into /versioned_docs/version-v2/ locally.

For v1:

• The /docs/ folder from 1.x branch needs to be cloned into /versioned_docs/version-v1/ locally.

@luisorbaiceta is this something you are able to work on? Thanks!

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

latest

Plugin version

Docusaurus version: 2.2.0

Node.js version

18.13.0

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

20.04

Description

when running npm run build:webuild , the error bellow is returned

[ERROR] Error: Missing generated file: static/generated/plugins.json. Run the "npm run build:website" once.
    at /home/edna/Desktop/bahati/Workspace/fastify/website-next/docusaurus.config.utils.js:27:13
    at Array.forEach (<anonymous>)
    at Object.checkGeneratedData (/home/edna/Desktop/bahati/Workspace/fastify/website-next/docusaurus.config.utils.js:24:18)
    at Object.<anonymous> (/home/edna/Desktop/bahati/Workspace/fastify/website-next/docusaurus.config.js:14:3)
    at Module._compile (node:internal/modules/cjs/loader:1218:14)
    at Module._extensions..js (node:internal/modules/cjs/loader:1272:10)
    at Module.load (node:internal/modules/cjs/loader:1081:32)
    at Module._load (node:internal/modules/cjs/loader:922:12)
    at Module.require (node:internal/modules/cjs/loader:1105:19)
    at module.exports (/home/edna/Desktop/bahati/Workspace/fastify/website-next/node_modules/import-fresh/index.js:32:59)

seems not to complain about this on commenting out 'static/generated/plugins.json', in https://github.com/fastify/website-next/blob/7bec1484ecf970aab3b9ba591869a48536e120ed/docusaurus.config.utils.js#L21

Steps to Reproduce

run npm run build:website

Expected Behavior

No response

We need the search button integrated into the website

🚀 As an exploration, we could try Lyra first: https://github.com/LyraSearch/plugin-docusaurus
It is a local and in-memory search, so it does not require any additional step or external system 🔝

If blocking issues are found on the first step, the current online website has the algolia plugin to enable the "search" button.
This plugin is already integrated into docusaurus. It requires some config only and keys (need to generate a key pair cc @lmammino ).

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

4.24.x

Plugin version

No response

Node.js version

18.16.0

Operating system

Windows

Operating system version (i.e. 20.04, 11.3, 10)

10

Description

I don't know if this is a design flaw or a bug but I noticed the below overlapping home link on the navbar when I tried to change to a tab view. It still shows on the nav menu list when you click the hamburger menu icon.

Browser: chrome

Steps to Reproduce

Change to mobile or tab view on your chrome browser.

Expected Behavior

The menu item should only be visible on the nav menu list on smaller screens. It should not overlap on both the nav menu list and the navbar.

I propose we include a page about useful / important talks, but also books, courses and useful resources.

As far as talks go, I'd recommend we add:

• https://www.youtube.com/watch?v=gltzZjKYK1I
• https://www.youtube.com/watch?v=ucatti2b7E4&list=PLAv2aQ9JgGbVAGY0ht6JMoGJ8tF_MJ4fx
• https://www.youtube.com/watch?v=g-6Ig8k6Nzc&pp=ygUOZmFzdGlmeSBzaGFwZXM%3D
• https://www.youtube.com/watch?v=e0rdy7APH-o
• https://www.youtube.com/watch?v=-X84Cq-nsLw
• https://www.youtube.com/watch?v=e1jkA-ee_aY&t=1s&pp=ygUOZmFzdGlmeSBzaGFwZXM%3D

They provide some commentary on why certain things are set up in this way, and I think they provide an integral part of the Fastify experience.

Most of those are from me with one from @delvedor. There are probably more that are worthwhile to include in this list.

On the live website: https://fastify.github.io/website-next/

The homepage organization section is broken:

1. Images:

2. Links:

We must use the <Link component and solve the image issue as well (not sure how)

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

We have to investigate the GDPR conformity.

• Avatars are externally loaded, load them when building and deploying?
• github stars and fork button should be not loaded from github, but prerendered?
• good-first-issues, is it conform that we load it?
• should we deploy daily the website with refreshed values or stars and avatars?

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

the fastify logo should be added to the landing page header section in place where we are having text Fastify as is at https://www.fastify.io/

Motivation

No response

Example

No response

We need to implement the Ecosystem page:

https://www.fastify.io/ecosystem/

Challenges

• Generate the plugin list
• Nice to have: add a filter under the Name and Description columns

Note that downloading the https://github.com/fastify/fastify/blob/main/docs/Guides/Ecosystem.md file is not in the scope of this task. You can assume that you have the markdown file in one directory. So, starting from there, you should be able to write a script that generates a JSON file that the new ecosystem page can render.

Tips

• Here is a snippet that parses the Ecosystem page and extracts the plugin list https://github.com/fastify/website/blob/master/src/scripts/processReleases.js#L316

Hi,
If you are reading this, you want to contribute to the new Fastify website: thank you!
This message explains all you need to know to join.

Useful links

• Project status: https://github.com/orgs/fastify/projects/5/views/1
• New website preview: https://fastify.github.io/website-next/

Contribute

If you want to contribute to this project, you can:

• write a comment on an open issue to be assigned to it
• open an issue with your suggestions

How to contribute

This repository follows the Fastify organization CONTRIBUTING and GOVERNANCE statements.

As a reminder: before working on an issue, be sure that:

• the issue is assigned to your account: wait for an admin reply
• the issue is clear to you: for any question you can drop a comment

To submit valuable changes to the project, you need to fork this repository and submit your code through a Pull Request. Here the step-by-step guides:

• How to fork
• How to submit a Pull Request

Project target

The target of this project is to redo the Fastify website: https://www.fastify.io/
Migrating to a new tech stack and new processes let the Fastify community contribute more easily to the documentation to let the Fastify web framework grow even more.

This journey was started by @Xhale1 and @luisorbaiceta, and all the credits till commit 3341dd3 and the work to sponsor this new project goes to them.

Tech Stack

The new website will be implemented with Docusaurus. It means that this project includes these topics:

• JSX
• bash scripting
• GitHub Action automation
• markdown manipulation

I'm not an expert on these topics. I'm just a "documentation reader" and a "pragmatic problem solver", so do not expect a TODO-LIST during a PR review, but a collaborative discussion 🤝

Project Boundaries

We can't just delete the old website and create a new one 😄 We must abide by these constraints:

1. we must ship fastify with the latest docs. Ref: https://github.com/fastify/fastify/tree/main/docs
2. we must deal with the old website links (eg: redirect)
3. a fastify contributor must update the docs on the main repo fastify/fastify (not on this repository)
4. we can't include any doc changes to fastify <=3

Nice to have

TRACKING PROJECT: https://github.com/orgs/fastify/projects/7

These features are not in the scope of this specific project - but we will try to implement the required features while keeping in mind the following list:

• New Getting started introduction
• internationalization
  • Korean https://github.com/fastify/docs-korean
  • Chinese https://github.com/fastify/docs-chinese
  • Portuguese https://github.com/fastify/docs-portuguese
• Migrate the blog from https://medium.com/@fastifyjs to this new website
• Helper: the user can search across GitHub issues

For sure, we are going to do them in a follow-up project at least 💯

PS: if the issue you are looking at has an empty description, it means that I'm still writing down the requirements, be patient and, meanwhile, fork the repository and start playing with it.. does it work in your local environment?

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

I propose to replace the text by the logo of the site in question.

Motivation

It makes it more "beautiful" (this is subjective). And around it makes the footer smaller so lighter on the brain.

Example

We can use Font Awesome

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

Have we considered combining the Fastify documentation site with the main Fastify package as a monorepo?

Motivation

Currently the Fastify repo contains the documentation source, while this repo contains the website source code. This (in my opinion) adds a considerable amount of overhead and difficulty for new contributors. For example, requiring the gh utility to be installed and setup struck me as unusual for a documentation site. As the original creator of this repo it took me longer than I'd expect to get to a point where I could preview the site in my browser (admittedly I'm sure that can improve without a monorepo).

I think it would be great if the markdown for the documentation, the website source code, and the core fastify code could all be located together. It could make getting started, previewing changes, and managing PR's more streamlined.

I'm certain I'm missing something here which would present a challenge. Very curious to hear thoughts.

Example

I setup a simple (incomplete) example in one of my repos over at https://github.com/hello-pangea/color-picker. It's built using turborepo.

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

Hi, @mcollina it seems like you are going to rewrite the website. If so I can help you with do that. Let me know the tech stack you'd like me to use and the setup.

Based on Fastify#2071, it seems that the overall agreement is the lack of structure of our documentation, rather than the precision or amount of documentation itself.

If we focus first on structuring our documentation in a way that is easier to filter, extend and manage; adding and improving documentation content/details should be an easier task for us and for any contributor of the project.

The structure that seems to be the most suggested is the Divio#Documentation Framework.
On a higher-level the structure seems nice, easier to filter, manage and extend.

We already have a set of sections in mind that we would like to converge, like Plugins, Guides, and References.
We can come with a mixed result based on the structure suggested an our needs.

Following the documentation and our current setup; I was imagine something similar to this:

• Documentation Home
• Technical Principles
• Use Cases
• Guides (should be ordered alphabetically)
  • Getting Started
  • v3 Migration Guide (shall we remove it?)
  • v2 Migration Guide (shall we remove it?)
  • The Hitchhiker's Guide to Plugins
  • Prototype Poisoning
  • Serverless
  • Testing
  • Write-Type-Provider
  • TypeScript Best Practices
  • Encapsulation
• References
  • Content Type Parser
  • Decorators
  • Errors
  • HTTP2
  • Hooks
  • LTS
  • Lifecycle
  • Logging
  • Middleware
  • Plugins
  • Reply
  • Request
  • Routes
  • Server
  • Type Providers
  • TypeScript
  • Validation and Serialization

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Description

At the organisations page, the link to Fastify website repository points to current website's repository, i think this should be pointing to this repository

Steps to Reproduce

Visit https://fastify.github.io/website-next/organisations

Expected Behavior

No response

The previous website is automatically regenerated every time there is a new release.
We should set the same thing up for this one too.
https://github.com/fastify/fastify/blob/main/.github/workflows/website.yml.

This is what we use in Platformatic: https://github.com/platformatic/platformatic/blob/main/.github/workflows/update-docs.yml.

We must work to improve the dev experience before working on this website takes days to run and build.

The issues to solve are:

• load a subset of versions to speed up the npm start command. Note that it exists the onlyIncludeVersions for this purpose
• generate static contents (plugins.json, benchmarks.json etc..) on the fly because the website will not start without these mandatories files
• suggestions?

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

Do you have stats for the site fastify.dev? I was in the same spot for my GitHub pages site so I built LibreCounter, a free, open site stats project that collects stats without cookies or tracking of any kind.

Only aggregates are stored for each site, page and day combination, so GDPR compliant (no personal data stored like IP addresses or user agents). Also no cookie warning necessary. Stats are public and available for everyone.

If you are interested I can implement a pull request, it's quite simple to integrate. No need to display the LibreCounter logo on the web pages, just a silent "pixel" of old. Since I have the site running anyway it's no additional cost for me, and also you can inspect the code (or even self-host) if needed.

You can also display an old fashioned counter or we can work out a custom solution if you want.

Let me know!

Motivation

I am guessing you don't have stats for the site fastify.dev, at least I don't know how to get them from GitHub pages. It can be useful to know how many visits you get every day, what pages are the most visited, where the visitors come from and so on. But having a cookie warning is a bummer, and also having to deal with the GDPR and the multiple legislations around the world. LibreCounter should provide an acceptable compromise with no tracking and no cookies.

LibreCounter uses Fastify by the way, so thanks for that! 🙏

Example

Stats would be visible at librecounter.org/fastify.dev/show:

Throughout the website, if you navigate your browser directly to a webpage (e.g. refresh the page or click a google result), it will redirect to having a trailing slash. However, if you navigate to any page using the website's internal navigation, it will not have a trailing slash. The docs pages include relative links which only work if the current page does not have a trailing slash. So if you follow a google result to a docs page and then click a relative link, it leads to a "Page Not Found".

Steps to Reproduce

1. Open https://fastify.dev/docs/latest/Guides/Getting-Started/ (possibly following a google result)
2. Click the link "the hitchhiker's guide to plugins" within the page (not the nav link)

Expected Behavior

The link works

Implement the contribute page:

https://www.fastify.io/contribute/

Challanges

• Integrate a plugin to get the Good first issues

Tips

What would I do?
I would look for an existing Docusaurus plugin or I would build it (instead of integrating custom logic here)

Note that the actual code from the old website should be easily migrated: https://github.com/fastify/website/blob/master/src/website/content/js/contribute.js

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

Current repo is missing a License file. Is this intentional or can it be added?

Hi @Eomm, I am opening this issue because i need help with addressing a force-push that just happened.

I was trying to open a pull request to address an issue #34 through #35. My fork showed there was a merge conflict so as i tried to solve it by following the leads given to undo 1 commit. Which i thought would undo my commit but instead triggered a force-push from f1ba71b to 4e3f356 .

Kindly help.

at https://fastify.github.io/website-next/ecosystem

We need to implement the index page you can see at:

https://www.fastify.io/

Todos

• hero header: I think it is done and working
• organization section
  • add a CSS filter to let the dark theme work
• core features
  • we must check all the links
  • check light/dark theme
• quick start section + Using CLI
• request/response validation and hooks
• TypeScript Support
• Buttons sections
• team section
• Acknowledgments section

Challenges

• Generate the organizations' layout
• Show some code snippets that switch between async/await **img2
• Generate the team layout

Tips

• the work of @luisorbaiceta can inspire you at https://github.com/fastify/website-next/blob/3341dd3131a01d7a8e1d3246c8ccb88f1ba9a88b/src/pages/index.tsx

Open Discussion

• Should we add a switch between CJS/ESM?
• Improve mobile layout (collaborators go from 3 columns to 1 columns instead of 3 -> 2 -> 1)

** img2

we must add a simple set of lining rules.

I see already a mismatch between filenames and quotes or double quotes

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the bug has not already been reported

Fastify version

Plugin version

Node.js version

Operating system

Linux

Operating system version (i.e. 20.04, 11.3, 10)

20.04

Description

Steps to Reproduce

Visit the https://fastify.github.io/website-next/ and click the Check out our benchmarks button

Expected Behavior

Expect it to navigate to https://fastify.github.io/website-next/benchmarks

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

Thoughts on switching from yarn to npm for this repo? It would match the original fastify site and because npm as the default option in nodejs it might offer a slightly lower barrier of entry.

Motivation

No response

Example

No response

whenever fastify/fastify#4938 will be merged, our script to generate the plugin page will break:

https://github.com/fastify/website/blob/main/scripts/build-plugin-list.js

This script needs to be updated accordingly.

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

Our CI pipeline is broken.

@Eomm
Could you have a look please?

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

Here is the current Core Web Vitals metrics and I think there is space for improvements

Motivation

With Fastify you raised the bar of the Node.js ecosystem for performance, usability, and much more.
I would like to help you to reach the same level on your website.
I have studied the repository and my proposal is to use Qwik to not provide JS at startup with a clear benefit for the CWV and usability for the end users.
I can work on this and create a new website to show you.

Example

No response

As done per v3 documentation in #48 we should manage the v2 documentation:

• build only one docs version for the latest v2 release that will be called v2.<latest minor>.x
• redirect all the old website links to the new documentation (as done per v3)
• check that the v2 pages are rendered correctly

The https://fastify.dev/benchmarks page lacks the last date we updated the data.
It would be cool to add it

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

Hello,

In this Docs link
I believe that the // remove additional properties comment is kind of unclear, meaning: when I read it I assumed that by default any additional properties would get removed automatically, which isn't the case.

Additional properties get removed only when their JSON Schema has additionalProperties: false, see this issue.

My suggestions is to simply change the comment to mention this small but important detail.

There's other places where removeAdditional is mentioned like here.

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the issue has not already been raised

Issue

I think it is important to know where we are, what has been done is obvious (great work btw!), but what needs to be done to have this ready. A good way would be to open issues for major things so any contributor can give us a hand and knows where to start.

WIP

• Docs
  • Fix darkmode font color
• Ecosystem
• Benchmarks

Migrate the benchmarks web page:

https://www.fastify.io/benchmarks/

Challanges

• Download the bench results
• Show the data in a nice way

In scope

Sometimes the bench repo doesn't work as shown in the image
Here the broken result file

In this case, we should ignore the results and go back in the file history to get the last valid one. Here a valid file example

This should work to get it:

• GET /repos/{owner}/{repo}/commits?path={file_path}
• GET /repos/{owner}/{repo}/git/commits/{commit_sha}
• GET /repos/{owner}/{repo}/git/blobs/{blob_sha}
• validate the file or next commit sha

After the website has its pages, we should check the SEO suggestions form docusaurus https://docusaurus.io/docs/seo and update the pages' metadata.

This includes:

• pages' metadata
• robot config
• sitemap

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

We should try to stick as much as possible to the current website design and iterate from there. As tempting as using a new tech stack and implementing new features can be, we have to think about the end user that is already familiar with the current website. Let's not forget that the goal of the site should just be update the stack and make it more maintainable in the long term

Motivation

No response

Example

No response

I was looking to turn on the hotkey:

Would you happen to know how?
(in case we may open a new dedicated issue)

Originally posted by @Eomm in #102 (comment)

If you try to search for "listen" in the website and click on the second result (server.listen()), the page that will load would have the anchor set, so it would not scroll down.

cc @ShogunPanda

Right now the workflow https://github.com/fastify/website-next/blob/main/.github/workflows/build_and_deploy.yml deploy to GH Pages the main code

By using a Github action and we should deploy a preview of the website into a temporary Github Pages environment, this would ease the test and feedback

I saw this app that should do the trick: https://github.com/marketplace/actions/deploy-pr-preview but I know it is doable without installing and app (and face security and access assessment). Here an example: npm/statusboard#615

Prerequisites

• I have written a descriptive issue title
• I have searched existing issues to ensure the feature has not already been requested

🚀 Feature Proposal

I propose to implement typescript in the project.

Motivation

It's better for security.

Ref:

https://docusaurus.io/docs/typescript-support