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

Automatically add .nojekyll file to support GitHub Pages #1680

Closed
srmagura opened this issue Sep 9, 2021 · 2 comments · Fixed by #1693
Closed

Automatically add .nojekyll file to support GitHub Pages #1680

srmagura opened this issue Sep 9, 2021 · 2 comments · Fixed by #1693
Labels
enhancement Improved functionality good first issue Easier issue for first time contributors

Comments

@srmagura
Copy link
Contributor

srmagura commented Sep 9, 2021

Search Terms

GitHub Pages, nojekyll, 404 error, page not found

Problem

A very common pitfall when serving TypeDoc documentation on GitHub Pages is getting 404 errors because of HTML file names that start with an underscore. Adding a .nojekyll file to your GitHub Pages root fixes this.

TypeDoc automatically clears your output folder, so your .nojekyll file will get removed. The best way to work around this is a custom package.json script that re-adds .nojekyll on every build:

"scripts": {
    "typedoc": "typedoc && touch docs/.nojekyll"
}

Suggested Solution

  1. Update the TypeDoc documentation to state that a .nojekyll file is necessary for your documentation site to work on GitHub Pages.
  2. Add a githubPages boolean config option that defaults to true. When githubPages == true, TypeDoc adds a .nojekyll file in the root of your output directory.

I can submit a PR if none of the maintainers are eager to work on this.

@srmagura srmagura added the enhancement Improved functionality label Sep 9, 2021
@Gerrit0 Gerrit0 added the good first issue Easier issue for first time contributors label Sep 10, 2021
@Gerrit0
Copy link
Collaborator

Gerrit0 commented Sep 10, 2021

Is this still necessary with TypeDoc 0.21+? Most of the underscores in file names in 0.20 and earlier were from module names that were wrapped with quotes. In 0.21+ we don't do that anymore, though I guess it could still show up if using scoped package names... it won't hurt anything, so sounds like a reasonable thing to include. A PR would be great!

@srmagura
Copy link
Contributor Author

Ah, I'm using scoped package names which is why I still have files beginning with underscores.

Will work on this when I get the time!

srmagura added a commit to srmagura/typedoc that referenced this issue Sep 12, 2021
This behavior is controlled by the new githubPages option which defaults to true.

Fixes TypeStrong#1680.
signedav added a commit to opengisch/slides-deployed that referenced this issue Mar 17, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement Improved functionality good first issue Easier issue for first time contributors
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants