Note that the preview site auto-generated for this PR is not built with the correctindex.html so it will not process Vue content as expected. To preview locally, check out the branch/PR and run the following:

node ./test/config/server.js --start

Public Changes

AddvueComponents configuration option
AddvueMounts configuration option
AddvueGlobalOptions configuration option
Add Vue 3 support
Add styling for<output> element tovue.css
Update/docs/ site

Dev Changes

There was a significant test-related bug fixed in this PR. Due to the way Jest manages the JSDOM environment, global objects like thewindow anddocument objects are not reset after each test in the same file. As a result, event listeners added to thewindow object by docsify were not being cleared after each test, resulting in event listeners from previous previous tests continuing to be triggered.

Add support todocsify-init() for functions inconfig
~~Add.markdownlint.json~~
Add_logHTML.selector option todocsify-init()
Remove unnecessary global variables from test environment
Remove--runInBand flag from local Jest tests
Update Vue tests
Update Jest cleanup/reset in/test/config/jest.setup-tests.js
FixwaitForSelector() timeout in/test/helpers/wait-for.js
Fixdocsify-init() handling ofconfig.basePath option

What kind of change does this PR introduce? (check at least one)

Bugfix
Feature
Code style update
Refactor
Docs
Build-related changes
Repo settings
Other, please describe:

If changing the UI of default theme, please provide thebefore/after screenshot:

Screenshot of new<output> styling (below code block):

Does this PR introduce a breaking change? (check one)

If yes, please describe the impact and migration path for existing applications:

The PR fulfills these requirements:

When resolving a specific issue, it's referenced in the PR's title (e.g.fix #xxx[,#xxx], where "xxx" is the issue number)

You have tested in the following browsers: (Providing a detailed version will be better.)

Chrome
Firefox
Safari
Edge
IE

If adding anew feature, the PR's description includes:

A convincing reason for adding this feature
Related documents have been updated
Related tests have been updated

jhildenbiddle added30 commits

October 9, 2020 23:14

Add vueOptions and vueGlobalOptions

35ad5c5

Fixed#752

Fix vueGlobalOptions.data checks

cd8f2d3

Support functions in docsify configuration

ecd053b

Fix Vue content detection and global options

5fa79eb

- Add detection of Vue HTML directives to trigger mounting- Fix bug that processed markdown child nodes as global Vue instances even if vueGlobalOptions is not specified- Fix bug that prevented passing vueGlobalOptions to global instances if `data()` prop did not exist- Update Vue config check to test for existence of object keys instead of just the existence object- Update tests

Add vueComponents support

a2386e5

Ignoreel property in Vue configs for Vue v2

bc2e091

Initial commit

1774ab8

Refactor regular expression usage

6d152e2

Add<output>. Refactor<pre> and<code>.

758538c

Update docs with new Vue features and usage

0193659

Fix directive detection

8a56f72

Update docs

5a2dde1

Update docs

1a52e97

RenamevueOptions tovueMountOptions

86dae61

Update test

2946c06

Update default waitForSelector value

871e48f

Fix waitForText() timeout and reject messages

131aae5

Change default startPath for tests & manual start

af7e713

Update jest/docsify side-effect cleanup

25084f8

Update directive detection (data vs static)

6a5e84b

Remove global event listeners beforeEach

febe7f8

Fix basePath

b6d5407

Remove unnecessary globals

8362ed0

Fix basePath update when config is function

f0a8d69

Fix basePath & update route URLs

5ec2256

Merge branch 'develop' into feat/vue-options

a9be6f2

Add selector option to _logHTML

3af1cfa

Remove SRC_PATH global variable

b33d750

Remove —runInBand flag from test script

cafdd62

Fix covepage test

d9e491a

trusktr reviewed

Nov 18, 2020

View reviewed changes

docs/vue.mdShow resolvedHide resolved

trusktr reviewed

Nov 18, 2020

View reviewed changes

docs/vue.md OutdatedShow resolvedHide resolved

trusktr reviewed

Nov 18, 2020

View reviewed changes

docs/vue.md Outdated

		1. Process unmounted Vue content using`vueGlobalOptions`
		- Docsify will not mount an existing Vue instance or an element that contains an existing Vue instance.
		- Docsify will automatically destroy/unmount all Vue instances it creates before new page content is loaded.
		- When processing`vueGlobalOptions`, docsify parses the child elements within the main content area (`#main`) and mounts the element if it contains Vue content. Docsify does not parse each individual node within the main content area.

Copy link

Member

trusktrNov 18, 2020

Choose a reason for hiding this comment

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

I'm not clear on the last bullet point. I guess if it'll start to explain this magic part, it might just need to go into more detail.

Copy link

MemberAuthor

jhildenbiddleNov 19, 2020

Choose a reason for hiding this comment

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

Yes, I agree this description could use some work. To be honest, I debated about even adding it. I've updated the description to (hopefully) make it more clear. At the end of the day, this text exists to help explain why this edge case won't work:

window.$docsify={vueGlobalOptions:{data(){return{globalMsg:'Hello from vueGlobalOptions!',};},},vueMounts:{'#test':{data(){return{mountMsg:'Hello from vueMounts!'};},},},};

Example 1: This will work

<!-- Source --><p>{{ globalMsg }}</p><pid="test">{{ mountMsg }}</p>

<!-- Output --><p>Hello from vueGlobalOptions!</p><pid="test">Hello from vueMounts!</p>

In this example, docsify first mounts the top-level<p> fromvueMounts. Docsify then iterates over the top-level child elements (<p>), skips the ones that contain or are themselves Vue instances, detects Vue template syntax in the top-level<p> element, and mounts it usingvueGlobalOptions. Great.

Example 2: This willnot work

<!-- Source --><div><p>{{ globalMsg }}</p><pid="test">{{ mountMsg }}</p></div>

<!-- Output --><div><p>{{ globalMsg }}</p><pid="test">Hello from vueMounts!</p></div>

Like the previous example, docsify first mounts the top-level<p> fromvueMounts. Docsify then iterates over the top-level child elements (<div>), detects that<div> contains a Vue instance (<p>) and skips that element. This behavior is explained in the following "Technical Notes" bullet point:

Docsify will not mount an existing Vue instance or an element that contains an existing Vue instance.

I think it is highly unlikely that this will be an issue, but I added the related technical notes in hopes of making life easier for everyone if it does. The trick is how to do this succinctly without going into the same level of detail above. Hopefully the changes I've put in place are good enough for now. We can always revisit if/when needed.

Copy link

Member

trusktrNov 24, 2020

Choose a reason for hiding this comment

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

@jhildenbiddle The example of what works vs what doesn't will be very helpful to some people. I think it'd be worth pasting what you wrote into the docs.