Question: Reasons for why 11ty is used over other available solutions #409

Andre601 commented 2024年03月15日 00:57:59 +01:00

This question was on my mind for a while now, so I finally want to ask it. And since it's about the Documentation do I think it's best suited here to ask.

My question is simple, but may have a complex answer: Why is 11ty used for the static site building over other solutions available like f.e. MkDocs, Docosaurus or other?
Are there specific benefits over the other options that make 11ty the best choice, or was it just a first pick?

I ask, because when I was contributing to the Documentation (i.e. adding callout boxes), getting 11ty to work and figuring everything out was tedious to achieve, which may be something other people might encounter too, discouraging them from contributing...
If there was no particular benefit/reason for 11ty, would Codeberg be open for moving the framework to something else?

This question was on my mind for a while now, so I finally want to ask it. And since it's about the Documentation do I think it's best suited here to ask. My question is simple, but may have a complex answer: Why is 11ty used for the static site building over other solutions available like f.e. MkDocs, Docosaurus or other? Are there specific benefits over the other options that make 11ty the best choice, or was it just a first pick? I ask, because when I was contributing to the Documentation (i.e. adding callout boxes), getting 11ty to work and figuring everything out was tedious to achieve, which may be something other people might encounter too, discouraging them from contributing... If there was no particular benefit/reason for 11ty, would Codeberg be open for moving the framework to something else?

Gusted commented 2024年03月15日 13:05:23 +01:00

It was once chosen, it has worked pretty well for the purposes Codeberg Docs need.

I ask, because when I was contributing to the Documentation (i.e. adding callout boxes), getting 11ty to work and figuring everything out was tedious to achieve, which may be something other people might encounter too, discouraging them from contributing...

Is this something specific to 11yt? I've not seen really good static sites builders where adding new features such as callout boxes could be done in an hour with no prior experience. Also most contributions come in the form of adding or improving existing content which are all in the markdown format.

If there was no particular benefit/reason for 11ty, would Codeberg be open for moving the framework to something else?

Moving to a new framework comes with its own problems and we would need to port our 'custom patches' to a new framework and make it compatible with the existing design choices.

Unless someone really wants to dedicate time and effort to improve the Codeberg documentations and moving to a new framework would help with that, then it would be fine but otherwise we shouldn't spend time or resources to things that already work.

It was once chosen, it has worked pretty well for the purposes Codeberg Docs need. > I ask, because when I was contributing to the Documentation (i.e. adding callout boxes), getting 11ty to work and figuring everything out was tedious to achieve, which may be something other people might encounter too, discouraging them from contributing... Is this something specific to 11yt? I've not seen really good static sites builders where adding new features such as callout boxes could be done in an hour with no prior experience. Also most contributions come in the form of adding or improving existing content which are all in the markdown format. > If there was no particular benefit/reason for 11ty, would Codeberg be open for moving the framework to something else? Moving to a new framework comes with its own problems and we would need to port our 'custom patches' to a new framework and make it compatible with the existing design choices. Unless someone really wants to dedicate time and effort to improve the Codeberg documentations and moving to a new framework would help with that, then it would be fine but otherwise we shouldn't spend time or resources to things that already work.

Andre601 commented 2024年03月15日 13:21:06 +01:00

Is this something specific to 11yt? I've not seen really good static sites builders where adding new features such as callout boxes could be done in an hour with no prior experience. Also most contributions come in the form of adding or improving existing content which are all in the markdown format.

Well, static site builders like Docosaurus or MkDocs already provide callouts that would only need to be added in configuration and doesn't need extra work, so there is already a difference to 11ty which seems to just be a bare-bones site builder here.

Moving to a new framework comes with its own problems and we would need to port our 'custom patches' to a new framework and make it compatible with the existing design choices.

And what patches would that be exactly? Maybe those are already included in alternative solutions?

> Is this something specific to 11yt? I've not seen really good static sites builders where adding new features such as callout boxes could be done in an hour with no prior experience. Also most contributions come in the form of adding or improving existing content which are all in the markdown format. Well, static site builders like Docosaurus or MkDocs already provide callouts that would only need to be added in configuration and doesn't need extra work, so there is already a difference to 11ty which seems to just be a bare-bones site builder here. > Moving to a new framework comes with its own problems and we would need to port our 'custom patches' to a new framework and make it compatible with the existing design choices. And what patches would that be exactly? Maybe those are already included in alternative solutions?

Gusted commented 2024年03月15日 15:08:14 +01:00

Well, static site builders like Docosaurus or MkDocs already provide callouts that would only need to be added in configuration and doesn't need extra work, so there is already a difference to 11ty which seems to just be a bare-bones site builder here.

It's good that dedicated solutions for documentation exists, but for all means and purposes 11ty has done a good job so far to provide a framework to do the same.

And what patches would that be exactly?

Anything that we've done on top of 11ty, such as the callouts and search.

Maybe those are already included in alternative solutions?

No clue, I don't see the benefit of exploring other solutions unless there comes something along that will make a compelling argument that another solution will help solving with problems that 11ty cannot solve, porting to another framework requires a lot of time and effort. Such as in the case if someone wants to dedicate time to improve Codeberg documentation and another framework provides more foundations to do that then porting it to a better solutions is fine. But just because those other solutions exists doesn't mean we have to use them, I really don't want anyone spend time on trying to port Codeberg documentations for no added benefit at this moment as docs.codeberg.org works without much thought at the moment, there are other problems that need attention in the Codeberg space.

> Well, static site builders like Docosaurus or MkDocs already provide callouts that would only need to be added in configuration and doesn't need extra work, so there is already a difference to 11ty which seems to just be a bare-bones site builder here. It's good that dedicated solutions for documentation exists, but for all means and purposes 11ty has done a good job so far to provide a framework to do the same. > And what patches would that be exactly? Anything that we've done on top of 11ty, such as the callouts and search. > Maybe those are already included in alternative solutions? No clue, I don't see the benefit of exploring other solutions unless there comes something along that will make a compelling argument that another solution will help solving with problems that 11ty cannot solve, porting to another framework requires a lot of time and effort. Such as in the case if someone wants to dedicate time to improve Codeberg documentation and another framework provides more foundations to do that then porting it to a better solutions is fine. But just because those other solutions exists doesn't mean we have to use them, I really don't want anyone spend time on trying to port Codeberg documentations for no added benefit at this moment as docs.codeberg.org works without much thought at the moment, there are other problems that need attention in the Codeberg space.