镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

Static docs - #1749

Merged
styfle merged 23 commits into
masterfrom
static-docs
Aug 31, 2020
Merged

styfle merged 23 commits into
masterfrom
static-docs

Conversation

@styfle

@styfle styfle commented Aug 17, 2020 •

Copy link
Copy Markdown
Member

Description

  • Change documentation to use SSG instead of SPA via npm run build:docs
  • Change page URLs to lowercase and use cleanUrls
  • Only uppercase markdown files are compiled to html pages
  • Add unique <title> to each page
  • Add syntax highlighting to code snippets
  • Add license as its own page instead of a link
  • Optimize svg logo, about 20% smaller
  • Redirect from old URL to new URL format

Contributor

Committer

In most cases, this should be a different person than the contributor.

  • Draft GitHub release notes have been updated.
  • CI is green (no forced merge required).
  • Merge PR

@vercel

vercel Bot commented Aug 17, 2020 •

Copy link
Copy Markdown

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/markedjs/markedjs/3jcxds3ly
✅ Preview: https://markedjs-git-static-docs.markedjs.vercel.app

@styfle

styfle commented Aug 17, 2020 •

Copy link
Copy Markdown
Member Author

@UziTech @joshbruce Do we want to use cleanUrls so the URLs look a bit prettier?

For example, it would change marked.js.org/using_advanced.html to marked.js.org/using_advanced

We could even rename this to just marked.js.org/advanced if we want to keep it really clean.

@UziTech

UziTech commented Aug 17, 2020

Copy link
Copy Markdown
Member

I prefer clean urls but I don't know if there is a benefit one way or the other.

We do need to make sure that old links are properly redirected.

@styfle

styfle commented Aug 17, 2020

Copy link
Copy Markdown
Member Author

I prefer clean urls too. We'll have to do the redirect on the client side since it needs to read the hash. I'll add that soon 👍

@joshbruce

Copy link
Copy Markdown
Member

I also prefer cleaner URLs from a UX perspective. Email link doesn't say https://marked.org/?page=12 but /play-with-marked or something - totally making stuff up as I do the inbox zero thing before a meeting.

@styfle
styfle marked this pull request as ready for review August 29, 2020 22:50

@davisjam davisjam left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a rubber stamp

Comment thread package.json
"lint": "eslint --fix bin/marked .",
"build:reset": "git checkout upstream/master lib/marked.js lib/marked.esm.js marked.min.js",
"build": "npm run rollup && npm run minify",
"build:docs": "node build-docs.js",

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this have to be called manually any time the docs are changed? Should we run this in the Build step on merge?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't commit the docs output so it doesn't need to run unless you want to see the docs output.

Would you prefer I rename this script to vercel-build instead of build:docs so its clear its for Vercel?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How does vercel know to run npm build:docs to get the output? and when does it run (on every PR, on every commit to master)?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The build command is configured here: https://vercel.com/markedjs/markedjs/settings

It runs every git push regardless of the branch. The master branch gets the production domain, https://marked.js.org, and PRs get the preview domains such as https://markedjs-git-static-docs.markedjs.vercel.app

@UziTech

UziTech commented Aug 31, 2020

Copy link
Copy Markdown
Member

Do we have documentation on how the documentation is built and where a markedjs member would go to edit it?

I like the idea of being able to use server side functions for the docs but I also like the simplicity of github pages and having all of the code/settings in a central place.

@styfle

styfle commented Aug 31, 2020 •

Copy link
Copy Markdown
Member Author

@UziTech You would go to https://vercel.com to edit project settings and https://vercel.com/docs for documentation.

It's arguably easier for a new user who has not used either GitHub Pages or Vercel before, because Vercel adds links to the PR so you know where it was deployed and which project to edit.

@styfle
styfle merged commit a41d8f9 into master Aug 31, 2020
@styfle
styfle deleted the static-docs branch August 31, 2020 21:01
@styfle styfle added the category: docs Documentation changes label Aug 31, 2020
@UziTech UziTech mentioned this pull request Sep 27, 2020
11 of 12 tasks
@github-actions

Copy link
Copy Markdown

🎉 This PR is included in version 1.1.2 🎉

The release is available on:

Your semantic-release bot 📦🚀

This branch was successfully deployed

1 active deployment
Preview — cf80141f Deployed Aug 29, 2020 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

category: docs Documentation changes released

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants