chore: Implement docs site

[nzakas]

Prerequisites checklist

• I have read the contributing guidelines.

What is the purpose of this pull request? (put an "X" next to an item)

[x] Documentation update
[ ] Bug fix (template)
[ ] New rule (template)
[ ] Changes an existing rule (template)
[ ] Add autofix to a rule
[ ] Add a CLI option
[ ] Add something to the core
[ ] Other, please explain:

What changes did you make? (Give an overview)

Added the files necessary to build a website from the docs directory. This is just the guts of the project to get us started so I can set up the site on Netlify and we can iterate from there. You can test by running npm install && npm start in the docs directory.

Is there anything you'd like reviewers to focus on?

Just make sure nothing is funky with the markdown files. I did my best to keep them as close to their current state, just with some additional frontmatter we are using in the new site and will be ignored in the current site.

[mdjermanovic]

Is the _site/ directory intentionally checked in, or should we add it to .gitignore?

[nzakas]

Oops, that should be added to .gitignore!

[mdjermanovic]

I tried to run npm run gensite on this branch. All the new directories inside docs/src/, like docs/src/library/, were copied to the website repo (the docFiles variable is effectively unused), and then npm run build in the website repo fails with "Problem writing Eleventy templates: You’re trying to use a layout that does not exist: components.html (undefined)". Assuming that we'll still be using the old (current) website after this week's release, we should probаbly fix Makefile.js to copy only the directories that should be copied to the website repo.

[nzakas]

Ah good call!

[mdjermanovic]

Copying files seems to work well now, but I'm getting the following error when running npm run build in the website repo:

Problem writing Eleventy templates: (more in DEBUG output)
> Output conflict: multiple input files are writing to `_site/index.html`. Use distinct `permalink` values to resolve this conflict.
  1. ./_pages/index.liquid
  2. ./docs/index.md

I'd guess the problem is that the permalink in the top index.md (docs/src/pages/index.md in this repo) should start with /docs for the current website. Maybe we don't actually need a permalink in that file?

When I undo the changes in that file, I'm getting errors for other files:

Problem writing Eleventy templates: (more in DEBUG output)
> Output conflict: multiple input files are writing to `_site/maintainer-guide/index.html`. Use distinct `permalink` values to resolve this conflict.
  1. ./docs/maintainer-guide/README.md
  2. ./docs/maintainer-guide/index.md

Maybe we could rename all README.md files to index.md, and then we won't need to add the permalink key?

[nzakas]

Maybe we could rename all README.md files to index.md, and then we won't need to add the permalink key?

Funny, that’s where I started. :) I was worried that renaming the file might cause problems but clearly not renaming the file causes problems.

[mdjermanovic]

The new site is now missing top index.html file (source file src/pages/index.md).

For some reason, on the current site that page isn't supposed to be accessible (there is a configured redirect), so maybe we could add back permalink: /index.html, but also exclude that file from copying to the current website (i.e., remove these lines) as it is effectively unused on the current website anyway.

[mdjermanovic]

edit_link should be updated (.../README.md -> .../index.md) in index.md files that were README.md files before this change:

• developer-guide/index.md
• maintainer-guide/index.md
• user-guide/configuring/index.md
• user-guide/index.md

[mdjermanovic]

There are still two README.md files:

• developer-guide/code-path-analysis/README.md - I think we can delete this one.
• developer-guide/contributing/README.md - This should probably be renamed to index.md.

[nzakas]

Thanks for catching all of that! I've made all those changes.

[mdjermanovic]

LGTM, I can confirm that gensite works well and that these changes do not affect the current site.

I didn't test the new site thoroughly (I understand we'll do that when we set up the site on Netlify), but one thing I've noticed is that path/to/something.md now always results in path/to/something/index.html, and consenquently the path on the website will be path/to/something/, while on the current site the file is path/to/something.html and path is path/to/something (doesn't end with /). This breaks some relative links, for example all Related Rules links in rule documents.

[nzakas]

Can you open an issue to that effect? I’ll take a look as I do my next pass.

[mdjermanovic]

Can you open an issue to that effect? I’ll take a look as I do my next pass.

Issue #15844