Skip to content

Commit 66feafe

Browse files
markbattistellamarkbattistella
authored
Merge pull request #5 from markbattistella/js-scope
v5.0.4 - fixes the global variable clashing
2 parents 144abc9 + 2899bd7 commit 66feafe

File tree

11 files changed

+255
-46
lines changed

11 files changed

+255
-46
lines changed

‎.github/README.md

Lines changed: 0 additions & 1 deletion
This file was deleted.

‎README.md

Lines changed: 185 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,185 @@
1+
<div align="center">
2+
3+
# docsify.js sidebar footer
4+
5+
</div>
6+
7+
This plugin enhances your website's sidebar or page by creating a footer area where you can display important information. It automatically updates the copyright year or range, allows you to include your name or company with a URL, and provides links to a privacy policy, terms of service, and cookies policy pages. By utilising this plugin, you can easily showcase relevant legal information, personalise your website, and promote transparency and compliance.
8+
9+
## Installation
10+
11+
!> **Note: There are breaking changes in the configuration from `v4.x` to `v5.x`. Please take the time to read all the documentation before upgrading**
12+
13+
### Update `index.html` file
14+
15+
Assuming you have a working [docsify](https://docsify.js.org/) framework set up, it is easy to use the plugin.
16+
17+
1. Add one of the following script tags to your `index.html` via either CDN or downloading it and using it locally:
18+
19+
```html
20+
<!-- unpkg.com -->
21+
<script src="https://unpkg.com/@markbattistella/docsify-sidebarfooter@latest"></script>
22+
23+
<!-- jsDelivr -->
24+
<script src="https://cdn.jsdelivr.net/npm/@markbattistella/docsify-sidebarfooter@latest"></script>
25+
26+
<!-- locally -->
27+
<script src="docsify-sidebar.min.js"></script>
28+
```
29+
30+
1. In docsify setup configure the plugin:
31+
32+
```js
33+
<script>
34+
window.$docsify = {
35+
autoFooter: {
36+
37+
// the name you wish to display as the copyright holder
38+
name: String,
39+
40+
// the URL (personal or company) which clicking the `name` goes to
41+
url: String,
42+
43+
// the start year of copyright
44+
copyYear: String,
45+
46+
// show the privacy policy link
47+
policy: Bool | String,
48+
49+
// show the terms of service link
50+
terms: Bool | String,
51+
52+
// show the cookies policy link
53+
cookies: Bool | String,
54+
55+
// use your own css styles or the built in ones
56+
customStyle: Bool | String
57+
}
58+
};
59+
</script>
60+
```
61+
62+
### Additional files
63+
64+
#### Default
65+
66+
If you set the `policy`, `terms`, or `cookies` options to `true` the URL links for those pages will look for the markdown files directly next to the `index.html` file:
67+
68+
```js
69+
// ... other config
70+
policy: true,
71+
terms: true,
72+
cookies: true,
73+
// ... other config
74+
```
75+
76+
```md
77+
- index.html --> https://your-awesome-site.com/#/
78+
- _policy.md --> https://your-awesome-site.com/#/_policy
79+
- _terms.md --> https://your-awesome-site.com/#/_terms
80+
- _cookies.md --> https://your-awesome-site.com/#/_cookies
81+
```
82+
83+
#### Sub-folder
84+
85+
However, if you enter a string it will append that to the base URL of your website:
86+
87+
```js
88+
// ... other config
89+
policy: 'site/policy',
90+
terms: 'site/terms',
91+
cookies: 'site/cookies',
92+
// ... other config
93+
```
94+
95+
```md
96+
- index.html --> https://your-awesome-site.com/#/
97+
- site/
98+
\__ policy.md --> https://your-awesome-site.com/#/site/policy
99+
\__ terms.md --> https://your-awesome-site.com/#/site/terms
100+
\__ cookies.md --> https://your-awesome-site.com/#/site/cookies
101+
```
102+
103+
#### External links
104+
105+
If you host your policy, terms, or cookies messages on an external website (or need to link to a parent company policy) you can add them in as the full URL:
106+
107+
```js
108+
// ... other config
109+
policy: "https://my-other-website.com/policy",
110+
terms: "https://my-other-website.com/terms",
111+
cookies: "https://my-other-website.com/cookies",
112+
// ... other config
113+
```
114+
115+
These will open those pages in a new tab directly.
116+
117+
## Configuration
118+
119+
There are some options available for the `docsify-sidebarfooter`:
120+
121+
| Setting | Type | Options |
122+
|---------------|----------------|------------------------------------|
123+
| `name` | String | your name or company |
124+
| `url` | String | url you want the `name` to link to |
125+
| `copyYear` | String | first year of copyright |
126+
| `policy` | Bool or String | - `false` hides it from the site<br/>- `true` defaults to `_policy.md`<br/>- a custom string will direct to that |
127+
| `terms` | Bool or String | - `false` hides it from the site<br/>- `true` defaults to `_terms.md`<br/>- a custom string will direct to that |
128+
| `cookies` | Bool or String | - `false` hides it from the site<br/>- `true` defaults to `_cookies.md`<br/>- a custom string will direct to that |
129+
| `customStyle` | Bool or String | - `false` uses in-built css (sidebar styled)<br/>- `true` applies no styles, you can create your own<br/>- `sidebar` uses the in-built css designed for the sidebar<br/>- `body` uses the in-built css designed for the body |
130+
131+
## Usage
132+
133+
### Sidebar
134+
135+
At the bottom of your `_sidebar.md` file add the following code:
136+
137+
```html
138+
<footer id="mb-footer"></footer>
139+
```
140+
141+
### Body
142+
143+
Under the `<div id="app"></div>` in your `index.html` file, add the following code:
144+
145+
```html
146+
<footer id="mb-footer"></footer>
147+
```
148+
149+
## Styling
150+
151+
The links container is sectioned into different classes for you to customise as much (or little) as you wish.
152+
153+
```html
154+
<footer id="mb-footer">
155+
<div class="footer-container">
156+
<div class="footer-text">
157+
<span class="footer-text-copyright">
158+
Copyright © YYYY-YYYY
159+
</span>
160+
<span class="footer-text-author">
161+
<a target="_blank" href="">Your website name</a>
162+
</span>
163+
</div>
164+
<div class="footer-link">
165+
<span class="footer-links-policy">
166+
<a href="">Policy</a>
167+
</span>
168+
<span class="footer-links-terms">
169+
<a href="">Terms</a>
170+
</span>
171+
<span class="footer-links-cookies">
172+
<a href="">Cookies</a>
173+
</span>
174+
</div>
175+
</div>
176+
</footer>
177+
```
178+
179+
## Contributing
180+
181+
1. Clone the repo:<br>`git clone https://github.com/markbattistella/docsify-sidebarFooter.git`
182+
2. Create your feature branch:<br>`git checkout -b my-feature`
183+
3. Commit your changes:<br>`git commit -am 'Add some feature'`
184+
4. `Push` to the branch:<br>`git push origin my-new-feature`
185+
5. Submit the `pull` request

‎dist/docsify-sidebar.min.js

Lines changed: 2 additions & 2 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎docs/README.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,8 @@ This plugin enhances your website's sidebar or page by creating a footer area wh
88

99
## Installation
1010

11+
!> **Note: There are breaking changes in the configuration from `v4.x` to `v5.x`. Please take the time to read all the documentation before upgrading**
12+
1113
### Update `index.html` file
1214

1315
Assuming you have a working [docsify](https://docsify.js.org/) framework set up, it is easy to use the plugin.

‎docs/dist/docsify-sidebar.js

Lines changed: 50 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
/*! docsify-sidebar.js v5.0.3 | (c) Mark Battistella */
1+
/*! docsify-sidebar.js v5.0.4 | (c) Mark Battistella */
22
'use strict';
33

44
// MARK: - check if object exists and is not empty
@@ -13,31 +13,44 @@ function doesObjectExists(obj) {
1313

1414

1515
// MARK: - update the `options` object
16-
function getFooter(options) {
16+
function getFooter(footerOptions) {
1717

1818
// -- get this year
1919
let date = new Date().getFullYear();
2020

2121
// -- update the variables
22-
options.name ? options.name : null;
23-
options.url ? options.url : null;
24-
options.copyYear ? options.copyYear : date;
25-
options.policy ? options.policy : false;
26-
options.terms ? options.terms : false;
27-
options.cookies ? options.cookies : false;
28-
options.customStyle ? options.customStyle : false;
22+
footerOptions.name ? footerOptions.name : null;
23+
footerOptions.url ? footerOptions.url : null;
24+
footerOptions.copyYear ? footerOptions.copyYear : date;
25+
footerOptions.policy ? footerOptions.policy : false;
26+
footerOptions.terms ? footerOptions.terms : false;
27+
footerOptions.cookies ? footerOptions.cookies : false;
28+
footerOptions.customStyle ? footerOptions.customStyle : false;
2929
}
3030

3131

32-
// defaults - and setup
33-
const options = {
32+
// -- defaults
33+
const footerOptions = {
3434
name: '',
3535
url: '',
3636
copyYear: '',
3737
policy: true,
3838
terms: true,
3939
cookies: true,
4040
customStyle: false
41+
},
42+
43+
// -- errors
44+
footerError = {
45+
46+
// -- error: when something that shouldn't happen, happens
47+
unknownError: 'ERROR: sidebar-footer plugin - unknown error',
48+
49+
// -- error: configuration not set
50+
configNotSet: `ERROR: sidebar-footer plugin - configuration not set\n\t\t>> this happens when the autoFooter is not found in the index.html file`,
51+
52+
// -- error: configuration is empty object
53+
configIsEmpty: `ERROR: sidebar-footer plugin - configuration is empty\n\t\t>> please consult the documentation for the settings needed`
4154
};
4255

4356

@@ -48,29 +61,29 @@ function autoFooter(hook, vm) {
4861
hook.init(function () {
4962

5063
// -- initialise the options
51-
getFooter(options);
64+
getFooter(footerOptions);
5265

5366

5467
// -- check the options for bool or string
55-
if (typeof options.customStyle === "boolean" || typeof options.customStyle === "string") {
68+
if (typeof footerOptions.customStyle === "boolean" || typeof footerOptions.customStyle === "string") {
5669

5770
// -- dont continue if using custom styles
58-
if ((typeof options.customStyle === "boolean" && options.customStyle === true)) {
71+
if ((typeof footerOptions.customStyle === "boolean" && footerOptions.customStyle === true)) {
5972
return;
6073
}
6174

6275
// -- global style
6376
let style = `#mb-footer { border-top: 1px solid; font-size: 0.8em; line-height: 1.5; transition: all var(--sidebar-transition-duration) ease-out; }`;
6477

6578
// -- custom style for sidebar
66-
if ((typeof options.customStyle === "boolean" && options.customStyle === false) ||
67-
(options.customStyle === "sidebar")
79+
if ((typeof footerOptions.customStyle === "boolean" && footerOptions.customStyle === false) ||
80+
(footerOptions.customStyle === "sidebar")
6881
) {
6982
style += `#mb-footer { padding-top: 1.5rem; margin-top: 1.5rem; } #mb-footer .footer-text, #mb-footer .footer-text a { font-weight: bold; }`;
7083
}
7184

7285
// -- custom style for sidebar
73-
if (options.customStyle === "body") {
86+
if (footerOptions.customStyle === "body") {
7487

7588
// --> if there is a sidebar
7689
if( $docsify.loadSidebar || $docsify.loadSidebar === null || !$docsify.hideSidebar ) {
@@ -173,17 +186,17 @@ function autoFooter(hook, vm) {
173186
// -- text
174187
copyright = (
175188
`<span class="footer-text-copyright">Copyright &copy; ${
176-
options.copyYear && options.copyYear <= date
177-
? `${options.copyYear}${options.copyYear < date ? "&#45;" + date : ""}`
189+
footerOptions.copyYear && footerOptions.copyYear <= date
190+
? `${footerOptions.copyYear}${footerOptions.copyYear < date ? "&#45;" + date : ""}`
178191
: date
179192
}</span>`
180193
),
181-
author = createLink( options.url, options.name, '', 'footer-text-author'),
194+
author = createLink( footerOptions.url, footerOptions.name, '', 'footer-text-author'),
182195

183196
// -- links
184-
policyURL = createLink(options.policy, 'Policy', '_policy', 'footer-links-policy'),
185-
termsURL = createLink(options.terms, 'Terms', '_terms', 'footer-links-terms' ),
186-
cookiesURL = createLink(options.cookies, 'Cookies', '_cookies', 'footer-links-cookies'),
197+
policyURL = createLink(footerOptions.policy, 'Policy', '_policy', 'footer-links-policy'),
198+
termsURL = createLink(footerOptions.terms, 'Terms', '_terms', 'footer-links-terms' ),
199+
cookiesURL = createLink(footerOptions.cookies, 'Cookies', '_cookies', 'footer-links-cookies'),
187200

188201
// output
189202
output = (
@@ -199,22 +212,27 @@ function autoFooter(hook, vm) {
199212

200213

201214
// MARK: - check options is defined and not empty
202-
if (typeof options !== 'undefined' && doesObjectExists(options)) {
215+
if (typeof footerOptions !== 'undefined' && doesObjectExists(footerOptions)) {
203216

204217
// -- find footer plugin options
205218
window.$docsify.autoFooter = Object.assign(
206-
options,
219+
footerOptions,
207220
window.$docsify.autoFooter
208221
);
209222
window.$docsify.plugins = [].concat(autoFooter, window.$docsify.plugins);
210223

211224
} else {
212225

213-
// -- log the error
214-
console.error(
215-
"ERROR: sidebar-footer configuration not set" + "\n" +
216-
"This error appears when:" + "\n" +
217-
" - the `autoSidebar` not found index.html file" + "\n" +
218-
" - the `autoSidebar` is empty"
219-
);
226+
// --> config not set in `index.html`
227+
if (typeof headerOptions === 'undefined') {
228+
throw footerError.configNotSet
229+
}
230+
231+
// --> config is empty object
232+
if (!doesObjectExists(headerOptions)) {
233+
throw footerError.configNotSet
234+
}
235+
236+
// --> some other error
237+
throw footerError.unknownError;
220238
}

0 commit comments

Comments
 (0)