Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation does not fully work with staticpkg #10292

Open
filips123 opened this issue Dec 1, 2024 · 0 comments
Open

Documentation does not fully work with staticpkg #10292

filips123 opened this issue Dec 1, 2024 · 0 comments

Comments

@filips123
Copy link

filips123 commented Dec 1, 2024

When building a PXT target with staticpkg, there are a number of issues with the documentation pages. These issues all happen when serving built/packaged from the root URL with a normal web server, but similar problems probably also happen when loading the editor from a subdirectory.

Links from the documentation sidebar do not work

When trying to open some documentation pages from the sidebar in a new, /docs/docs/about.html is opened instead of /docs/about.html. This happens for pages opened from the navigation menu (which are specified in docMenu inside pxtarget.json), but works fine for some other pages.

The issue was supposed to be fixed in #4700 and #4717, but it is still present in PXT 11.3.4.

To reproduce:

  1. Build the target with staticpkg.
  2. Open the editor.
  3. Open the documentation page from the navigation menu:
    Image
  4. Click the "open in new tab" button.
  5. See that you are redirected to /docs/docs/about.html, which doesn't exist.

Another place where opening pages from the sidebar doesn't work is the blocks reference page:

  1. Build the target with staticpkg.
  2. Open the editor.
  3. Open the "blocks" page from the navigation menu.
  4. Open the "loops" category card.
  5. Click the "open in new tab" button.
  6. See that you are redirected to /docsblocks/loops.html, which doesn't exist.

This also happens for URLs like /docsreference.

Clicking on cards in the documentation does not work

When clicking on a block/category/tutorial card in the documentation, you are redirected to the incorrect URL.

For example, when clicking on the "arrays" card on the blocks page (/docs/blocks.html), /reference/arrays is opened instead of /docs/reference/arrays.html. Or, when clicking on the "for loop" card on the loops page (/docs/blocks/loops.html), you are redirected to /blocks/loops/while instead of /docs/blocks/loops/while.html. This issue seems to happen for all cards in the standalone documentation, but works fine for the documentation inside the sidebar.

To reproduce:

  1. Build the target with staticpkg.
  2. Open the blocks documentation page (/docs/blocks.html).
  3. Click on any card.

All documentation pages have the same title

All documentation pages have the same title (which appears to be title from the pxtarget.json), with no way to set a per-page title.

Documentation localization is not supported

All documentation pages have lang="en" attribute set, and all content is in English, even if a different language is selected.

Embedding blocks does not work and some URLs are incorrect

Embedding blocks as described on the blocks embed page does not work. Additionally, on various places, URLs like --docs and --asseteditor are hardcoded, instead of docs.html and asseteditor.html.

Images in documentation are not loaded properly

Any relative image URL in documentation gets converted to an URL like /static/images/example.png, even though the correct URL is /docs/static/images/example.png.

Some icons are not loaded correctly

Some icons, for example the Google Classroom icon on the sharing page, are not loaded, as they are loaded from the /static/logo/social-buttons/google-classroom.png instead of /docs/static/logo/social-buttons/google-classroom.png.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant