usethesource / rascal-website Goto Github PK

I found a small typo on the priorities page.

here no backticks have been added for the code fragment on the last line. Because of this, * is interpreted as italic start and end marks.

I just noticed that the toJSON function is @deprecated in the source code, but that is not present on the document page of it is that something we can add there?

https://www.rascal-mpl.org/docs/GettingStarted/DownloadAndInstallation/ does not mention which version of the JDK is needed in order for Rascal to run.

In case, the VS Code extension fails to setup the right JDK (see here), this can be helpful information for debugging and understanding.
The JDK is mentioned in the extension description (and here), but can be easily overlooked

Currently we are lacking some meta data to get nicer rendered URL preview:

https://www.opengraph.xyz/url/https%3A%2F%2Fwww.rascal-mpl.org%2F

/stable/ and /unstable/ subdirs

Any CSS heroes ready to answer this call for help?

Hi,

The new docs are easier to browse, and in general a big improvement over the previous website!
One thing I run into every now and then is that some of the generated pages are less informative than the source files from which they are generated, such as https://www.rascal-mpl.org/docs/Packages/salix-contrib/API/salix/ace/Demo/. Here the sections function update and function view don't tell us much, but their full sources are quite informative.

I think it would be useful to have a link on the page that refers to the source the documentation page was derived from, in this case https://github.com/usethesource/salix-contrib/blob/main/src/main/rascal/salix/ace/Demo.rsc.

1. Put a link to the reference library on the homepage
2. Use terminology people are used to. When I encounter a new proglang, I want to dive in the docs fast. With Rascal I have to click 'help' (which for me means: contact somebody) and then 'tutor' (which means nothing to me, I'm looking for docs). And in Tutor I have to click 'Rascal: Language and libraries' instead of 'reference documentation'. As a new developer, you would have lost me.
3. Don't open links in new windows (I can decide myself if I want to open in a new tab/window nowadays)
4. Put the version number for which rascal version the docs are, in the footer of the docs

I've found a couple of mistakes in the markdown formatting (at least according to github and docusaurus' parsers).
Apparently | is not allowed in a code block within a table, without escaping it.

This causes issues here: Associativity.md?plain=1#L74
Which can be fixed by writing the following instead:

| `E = left ( "+" E \| E "+" E );` | `E = E "+" E > "+" E;`  |
| `E = right ( "+" E \| E "+" E );` | `E = "+" E > E "+" E;`  |
| `E = left ( E "+" \| E "+" E);` | `E = E "+" > E "+" E;`  |
| `E = right ( E "+" \| E "+" E);` | `E = E "+" E > E "+" ;` |

The same applies here: Regular.md?plain=1#L98

There may be another couple of pages, like this, but these are the ones I encountered.

I am not a 100% sure if this properly fixes the issue though. It does fix it in github, but it seems docusaurus may not be getting rid of the escapement \ properly, given that at the very bottom of the operators page the \ is still present: https://www.rascal-mpl.org/docs/Rascal/Expressions/Operators/ .

The links on /start/ are invalid / not working.

I'd like to have this feature, especially useful for screenshots: https://gabrielcsapo.github.io/docusaurus-plugin-image-zoom/docs/getting-started/

Tried it quickly. didn't work.

If you open the https://www.rascal-mpl.org there is no direct link to go an download/install rascal

As reported by @jurgenvinju, many screenshots are not created OK, eg. on https://www.rascal-mpl.org/docs/Library/vis/Charts/ there are white squares.

Locally everything working according to @jurgenvinju. It's only on the GitHub Actions runners going wrong.

Probably selenium not waiting long enough (page ready?).

I don't know where to look for this issue, but I want to report it here so others can see it's a known issue.

https://www.rascal-mpl.org/docs/Rascal/Declarations/SyntaxDefinition/Disambiguation/

Browser still shows the old Rascal logo (wasp) as favicon. Replace this by favicon for new logo.

We have quite some reports about our sitemap having urls that are then redirected to the "canonical" url, apparently google doesn't like it.

and indeed, if you check, in the sitemap.xml there is:

<url>
<loc>https://www.rascal-mpl.org/docs/Library/Set/</loc>
<changefreq>weekly</changefreq>
<priority>0.5</priority>
</url>

but if you request that url you get back a result, but with a different location:

 curl -v https://www.rascal-mpl.org/docs/Library/Set/ > /dev/null
... snip
< etag: "65b63e598821e3c3446c16ab08ba816f-ssl"
< location: /docs/library/set/
< server: Netlify
< strict-transport-security: max-age=31536000
<

maybe this is a normalisation happening at netlify? or on our end?

It's not part of the typelatice, there is no separate section, only mention of it is arbRat in util::Math

There are some anchor tags not being processed properly. I think we need to normalize or remove the special characters.

[ERROR] Unable to build website for locale en.
[ERROR] Error: Docusaurus found broken links!

Please check the pages of your site in the list below, and make sure you don't reference any path that does not exist.
Note: it's possible to ignore broken links with the 'onBrokenLinks' Docusaurus configuration, and let the build pass.

Exhaustive list of all broken links found:

- On source page path = /docs/Library/ParseTree/:
   -> linking to ../Library/ParseTree.md/#ParseTree-parse (resolved as: /docs/Library/Library/ParseTree.md/)
   -> linking to ../Library/ParseTree.md/#ParseTree-treeAt (resolved as: /docs/Library/Library/ParseTree.md/)

    at throwError (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/logger/lib/index.js:76:11)
    at handleBrokenLinks (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/core/lib/server/brokenLinks.js:153:47)
    at async buildLocale (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/core/lib/commands/build.js:177:5)
    at async tryToBuildLocale (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/core/lib/commands/build.js:38:20)
    at async mapAsyncSequential (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/utils/lib/jsUtils.js:34:24)
    at async Command.build (/Users/jurgenv/Sites/rascal-website/node_modules/@docusaurus/core/lib/commands/build.js:73:21)

There are many other links in the document that do work. I don't see the difference with these:

...
Tree search result type for [Tree At](../Library/ParseTree.md#ParseTree-treeAt)
...
This function is similar to the [Parse](../Library/ParseTree.md#ParseTree-parse) function in its functionality.
...

Note I'm quoting from the tutor-generated docs folder with the markdown input for docusaurus.

I'm baffled. Maybe @JJWTimmer; do you see what is going on here?