microsoft / microsoft/pxt

Documentation does not fully work with staticpkg

Open
#10,292 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
2.3k
Forks
641
Avg merge
12h 4m
Merged PRs (30d)
57

Description

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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reproducing a staticpkg build and serving built/packaged from the root URL, using pxtarget.json and its docMenu entries as the initial references. Trace the generated documentation links, titles, localization, embeds, images, and icons across the listed /docs paths. Done means the documented static package flows work with correct URLs, per-page titles, selected-language content, embeds, and assets.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
build-system, documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.