Ben Goldsworthy
e8d6dbe13d
* Adapt after the 2.5.9d1 accident. * Corrections to changelog. * Also added @revision and @timestamp PHPDOC tags @revision and @timestamp used for SVN refs. Full enumeration of added custom PHPDOC tags: @accountable, @bib, @biblio, @callback, @commit, @committer, @contributor, @courtesy, @date, @datetime, @lastmodified, @modified, @publisher, @reporter, @revision, @timestamp, @user.Some tags like @reporter and @contributor are more used than others. * Readme header upgrade. * Create deploy-to-wordpress.org.yml * Add distignore * Comment out `build` command, replace npm with composer * Remove placeholder comments * Add build commands * Fix typo * Fix version number bug * Make zip without top-level directory * Append tag name to plugin zip * Clean up a bit * Rename workflow config * Fix upload paths * Append tag name to artifact * Fix paths * Revert path fix * Try again * Add wplm-config.xml to buildfiles * Fix indentation * Rename development/csscat.sh to css/csscat.sh * Rename development/customized-documentation-schema.txt to customized-documentation-schema.txt * Rename development/customized-template-stack.txt to customized-template-stack.txt * Version number related fixes before pull request. * Move csscat script to tools dir * Rename csscat * Refactor script * Update customized-documentation-schema.txt * Replace empty lines in help output * Escape empty lines. * Delete 3 items from `.distignore` As mentioned, CONTRIBUTING.md and README.md should be included in distributions. - As an invitation to the Community. - As a tangible proof of goodwill after the 2.5.9d1 accident. Also SECURITY.md so Footnotes users see that we’re concerned, and can reach out without transiting via GitHub. * Include CONTRIBUTING.md README.md SECURITY.md * Update sync w/ 5.7 tested. * Update * Update composerfiles Co-authored-by: pewgeuges <73141620+pewgeuges@users.noreply.github.com>
81 lines
4.1 KiB
Markdown
81 lines
4.1 KiB
Markdown
|
|
|
|
# footnotes
|
|
|
|
## Description
|
|
|
|
Featured on [wpmudev](http://premium.wpmudev.org/blog/12-surprisingly-useful-wordpress-plugins-you-dont-know-about/) --- cheers for the review, folks!
|
|
|
|
**footnotes** aims to be the all-in-one solution for displaying an automatically generated list of references on your Page or Post. The Plugin ships with a set of defaults while also empowering you to control how your footnotes are being displayed.
|
|
|
|
**footnotes** gives you the ability to display well-formatted footnotes on your WordPress Pages and Posts — those footnotes we know from offline publishing.
|
|
|
|
## Getting Started
|
|
|
|
1. Read the contributing guidelines
|
|
1. Clone this repository (`git clone git@github.com:markcheret/footnotes.git`)
|
|
- We recommend that you use [VVV](https://varyingvagrantvagrants.org/) for your development environment
|
|
1. Install [Composer](https://getcomposer.org/download/), if you don't have it already
|
|
1. Install dependencies (`composer install`)
|
|
1. Create a new branch from `main` (`git checkout -b <your-descriptive-branch-name>`)
|
|
1. When you're finished, commit your changes to the remote version of your branch
|
|
and submit a [pull request](https://github.com/markcheret/footnotes/pulls).
|
|
|
|
## Checking WP Coding Standard Compliance
|
|
|
|
1. Run PHP_CodeSniffer on the file(s) you want to check (`./vendor/bin/phpcs --standard="WordPress" --colors --encoding=utf-8 -n -p <file(s)>`)
|
|
1. (If applicable) run the PHP Code Beautifier and Formatter to attempt to automatically fix any errors (`./vendor/bin/phpcbf --standard="WordPress" --encoding=utf-8 -p <file(s)>`)
|
|
- Add the `-n` flag to ignore warnings (i.e., show only errors)
|
|
- Add the `-s` flag to show sniff codes (used for disabling errors in the code with `phpcs disable:<sniff code>` — MAKE SURE THAT YOU HAVE `phpcs enable` AT THE EARLIEST POINT POSSIBLE, and provide a justification for disabling the sniff code)
|
|
- You can run either across the entire project by adding the argument `--ignore=*/vendor/*` and targetting the file `./**/*.php`
|
|
- You may have to enable double-wildcards in your console first (`shopt -s globstar`)
|
|
|
|
## Building
|
|
|
|
1. Run `_tools/build-stylesheets.sh -c` to concatenate stylesheets
|
|
1. Manually minify the output files in `css/tmp/`, saving them as `.min.css` files
|
|
- The intention is to replace this with automated minification, meaning that
|
|
all of these steps can be rolled into a single `build` command.
|
|
1. Run `_tools/build-stylesheets.sh -d` to deploy the minified files to `dist/`
|
|
- **this will delete any existing `dist/` folder**
|
|
1. Run `composer run build` to move over the remaining files to `dist/`
|
|
- Currently, the files to include in a distribution are hard-coded in `_tools/build.sh`
|
|
- The intention is to replace this with a proper parsing of the `.distignore` file
|
|
|
|
## Updating Documentation
|
|
|
|
1. Install [phpDocumentor](https://phpdoc.org/)
|
|
1. Run it (`phpDocumentor -d . -t docs`)
|
|
|
|
## Testing
|
|
|
|
Unit tests are TODO.
|
|
|
|
## Main Features
|
|
|
|
- Fully customizable **footnotes** start and end shortcodes;
|
|
- Styled tooltips supporting hyperlinks display **footnotes** or a dedicated text;
|
|
- Responsive *Reference Container* at the end or positioned by shortcode;
|
|
- Display the **footnotes** *Reference Container* inside a Widget;
|
|
- Wide choice of numbering styles;
|
|
- Freely configurable and optional backlink symbol;
|
|
- Configure the **footnotes'** appearance by dashboard settings and Custom CSS style rules;
|
|
- Button in both the Visual and the Text editor to add shortcodes around selection.
|
|
|
|
## Example Usage
|
|
|
|
These are a few examples of possible ways to delimit footnotes:
|
|
|
|
1. Your awesome text((with an awesome footnote))
|
|
2. Your awesome text[ref]with an awesome footnote[/ref]
|
|
3. Your awesome text`<fn>`with an awesome footnote`</fn>`
|
|
4. Your awesome text`custom-shortcode`with an awesome footnote`custom-shortcode`
|
|
|
|
## Where to get footnotes?
|
|
|
|
The current version is available on the [WordPress.org Plugin Directory](https://wordpress.org/plugins/footnotes/).
|
|
|
|
## Acknowledgements
|
|
|
|
Huge thanks to every **footnotes user**, contributor, bug reporter, feature requester and fan!
|