footnotes/README.md

footnotes

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 will be displayed.

footnotes gives you the ability to display well-formatted footnotes on your WordPress Pages and Posts — those footnotes we know from offline publishing.

Featured on wpmudev — cheers for the review, folks!

Table of Contents

• Features
• Getting Started
• Deploying
• Testing
• Code Formatting
• Documentation
• Acknowledgments
• License
• Contact Information

Features

This Plugin provides:

• fully customizable footnote start and end shortcodes;
• stylable tooltips supporting hyperlinks and dedicated text;
• a responsive 'reference container', with customisable positioning;
• a wide choice of different numbering styles;
• a freely-configurable and optional backlink symbol;
• footnote appearance customisation via dashboard settings and custom CSS style rules; and
• editor buttons for easily adding shortcode tags.

Getting Started

1. Read the contributing guidelines;
2. clone this repository (git clone git@github.com:markcheret/footnotes.git):
   • we recommend that you use VVV for your local testing environment.
3. install Composer and NPM; and
4. install all dependencies (composer install):
   • you will have to install php-mbstring manually if you do not already have it.

Deploying

Automated release deployments will be introduced soon.

Building

1. Run _tools/build-stylesheets.sh -c to concatenate stylesheets;
2. 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.
3. run _tools/build-stylesheets.sh -d to deploy the minified files to dist/:
   • this will delete any existing dist/ folder!
4. 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; but
   • the intention is to replace this with a proper parsing of the .distignore file

Releasing

1. Ensure that you have configured your Git config. with SVN credentials;
2. run the above build commands; and
3. run composer run release and follow the prompts.

Testing

Automated testing will be introduced soon.

Code Formatting

This repo. uses pre-commit code formatting and linting on all staged files. This ensures that only style-conformant code can be committed.

The individual commands can also be called manually:

• Run composer run format to run all format commands.

• Run composer run format:fix to attempt to automatically fix all formatter warnings and errors.

• Run composer run lint to run all linting commands.

• Run composer run lint:fix to attempt to automatically fix all linter warnings and errors.

PHP Code

PHP code must follow the WordPress PHP Coding Standards.

1. Run composer run lint:php to lint all JS/TS files with PHP CodeSniffer
2. Run composer run lint:php:fix to attempt to automatically fix warnings and errors with the PHP Code Beautifier and Formatter.

JavaScript Code

JavaScript code must follow the WordPress JavaScript Coding Standards.

• Run composer run format:js to format all JS files with Prettier.

• Run composer run format:js:fix to attempt to automatically fix warnings and errors.

• Run composer run lint:js to lint all JS files with ESLint.

• Run composer run lint:js:fix to attempt to automatically fix warnings and errors.

Prettier configuration settings are found in .prettierrc.

ESLint configuration settings are found in .eslintrc.js. File ignore rules are found in .eslintignore.

CSS Stylesheets

JavaScript code must follow the WordPress CSS Coding Standards.

• Run composer run lint:css to format all CSS files with stylelint.
• Run npcomposerm run lint:css:fix to attempt to automatically fix warnings and errors.

stylelint configuration settings are found in .stylelint.json.

Documentation

Run composer run docs to automatically generate HTML documentation with phpDocumentor.

View the current docs here.

Acknowledgements

Huge thanks to every footnotes user, contributor, bug reporter, feature requester and fan!

License

This project is licensed under the GNU GPL v3.

Contact Information

Name	Link(s)
Mark Cheret	Email