Hopiu/djLint
1
0
Fork 0
mirror of https://github.com/Hopiu/djLint.git synced 2026-05-02 02:44:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs update

Browse source
This commit is contained in:
Christopher Pickering 2021-12-01 10:13:09 +01:00
parent 894b17ba24
commit a260b8c063
No known key found for this signature in database
GPG key ID: E14DB3B0A0FACF84
9 changed files with 166 additions and 165 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/djlint/best_practices.rst
View file

@ -1,3 +1,9 @@
.. meta::
:title lang=en: djLint » Best Practices
:description lang=en:
Best practices for using djLint to format HTML templates.
:keywords lang=en: template linter, template formatter, djLint, HTML, templates, formatter, linter, best practices
Best Practices
==============

6
docs/djlint/changelog.rst
View file

@ -1,3 +1,9 @@
.. meta::
:title lang=en: djLint » Changelog
:description lang=en:
djLint Changelog.
:keywords lang=en: template linter, template formatter, djLint, HTML, templates, formatter, linter, changelog
Changelog
=========

7
docs/djlint/configuration.rst
View file

@ -1,3 +1,10 @@
.. meta::
:title lang=en: djLint » Configuration
:description lang=en:
djLint configuration for HTML Template Linting and Formatting.
Take advantage of the many formatter options.
:keywords lang=en: template linter, template formatter, djLint, HTML, templates, formatter, linter, configuration
Configuration
=============

11
docs/djlint/formatter.rst
View file

@ -1,5 +1,12 @@
Formatter
=========
.. meta::
:title lang=en: djLint » Formatter Usage
:description lang=en:
Format your HTML Templates with djLint. Fast, accurate, output
will make your templates shine.
:keywords lang=en: template linter, template formatter, djLint, HTML, templates, formatter, linter, formatter usage
Formatter Usage
===============
djLint's formatter will take sloppy html templates and make it look pretty nice!

127
docs/djlint/usage.rst → docs/djlint/getting_started.rst
View file

@ -1,13 +1,48 @@
.. meta::
:title lang=en: djLint » Getting Started
:description lang=en:
Getting started with djLint for HTML Template Linting and Formatting.
Take advantage of the easy cli interface and many formatter options.
:keywords lang=en: template linter, template formatter, djLint, HTML, templates, formatter, linter, usage
Getting Started
================
Installation from `Pypi <https://pypi.org/project/djlint/>`__
--------------------------------------------------------------
.. code:: sh
.. code:: bash
pip install djlint
CLI Usage
---------
djLint is a command line application. See `configuration </djlint/configuration.html>`_ for advanced configuration.
.. code:: sh
Usage: python -m djlint [OPTIONS] SRC ...
djLint · lint and reformat HTML templates.
Options:
--version Show the version and exit.
-e, --extension TEXT File extension to check [default: html]
-i, --ignore TEXT Codes to ignore. ex: "H014,H017"
--reformat Reformat the file(s).
--check Check formatting on the file(s).
--indent INTEGER Indent spacing. [default: 4]
--quiet Do not print diff when reformatting.
--profile TEXT Enable defaults by template language. ops: django,
jinja, nunjucks, handlebars, golang
--require-pragma Only format or lint files that starts with a comment
with the text 'djlint:on'
--lint Lint for common issues. [default option]
--use-gitignore Use .gitignore file to extend excludes.
-h, --help Show this message and exit.
Linter Usage
------------
@ -23,8 +58,6 @@ Formatter Usage
Formatting is a beta tool. ``--check`` the output before applying changes.
Reformatting does not work with long json/html embedded into attribute data.
To review what may change in formatting run:
.. code:: sh
@ -37,6 +70,12 @@ To format the code and update files run:
djlint . --reformat --indent=3
.. note::
Reformatting does not work with long json/html embedded into attribute data.
Ignoring Code
-------------
@ -93,85 +132,3 @@ Output -
.. code:: html
<div></div>
CLI Args
--------
.. code:: sh
Usage: python -m djlint [OPTIONS] SRC ...
djLint · lint and reformat HTML templates.
Options:
--version Show the version and exit.
-e, --extension TEXT File extension to check [default: html]
-i, --ignore TEXT Codes to ignore. ex: "H014,H017"
--reformat Reformat the file(s).
--check Check formatting on the file(s).
--indent INTEGER Indent spacing. [default: 4]
--quiet Do not print diff when reformatting.
--profile TEXT Enable defaults by template language. ops: django,
jinja, nunjucks, handlebars, golang
--require-pragma Only format or lint files that starts with a comment
with the text 'djlint:on'
--lint Lint for common issues. [default option]
--use-gitignore Use .gitignore file to extend excludes.
-h, --help Show this message and exit.
As a pre-commit hook
--------------------
djLint can also be used as a `pre-commit <https://pre-commit.com>`_ hook.
The repo provides multiple pre-configured hooks for specific djLint profiles (it just pre-sets the ``--profile`` argument and tells pre-commit which file extensions to look for):
* ``djlint-django`` for Django templates:
This will look for files matching ``templates/**.html`` and set ``--profile=django``.
* ``djlint-jinja``
This will look for files matching ``*.j2`` and set ``--profile=jinja``.
* ``djlint-nunjucks``
This will look for files matching ``*.njk`` and set ``--profile=nunjucks``.
* ``djlint-handlebars``
This will look for files matching ``*.hbs`` and set ``--profile=handlebars``.
* ``djlint-golang``
This will look for files matching ``*.tmpl`` and set ``--profile=golang``.
Note that these predefined hooks are sometimes too conservative in the inputs they accept (your templates may be using a different extension) so pre-commit explicitly allows you to override any of these pre-defined options. See the `pre-commit docs <https://pre-commit.com/#pre-commit-configyaml---hooks>`_ for additional configuration
Default Django example
^^^^^^^^^^^^^^^^^^^^^^
.. code:: yaml
repos:
- repo: https://github.com/Riverside-Healthcare/djLint
rev: 0.5.10 # grab latest tag from GitHub
hooks:
- id: djlint-django
Handlebars with .html extension instead of .hbs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: yaml
repos:
- repo: https://github.com/Riverside-Healthcare/djLint
rev: 0.5.10 # grab latest tag from GitHub
hooks:
- id: djlint-handlebars
files: "\\.html"
You can use the ``files`` or ``exclude`` parameters to constrain each hook to its own directory, allowing you to support multiple templating languages within the same repo.

9
docs/djlint/integrations.rst
View file

@ -1,3 +1,10 @@
.. meta::
:title lang=en: djLint » Integrations
:description lang=en:
Integrate djLint with your favorite editor. Auto format
your templates with Pre-Commit. Lint with SublimeText.
:keywords lang=en: template linter, template formatter, djLint, HTML, templates, formatter, linter, integrations
Integrations
============
@ -45,7 +52,7 @@ Default Django example
Handlebars with .html extension instead of .hbs
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
.. code:: yaml

145
docs/djlint/rules.rst → docs/djlint/linter_rules.rst
View file

@ -1,78 +1,85 @@
.. meta::
:title lang=en: djLint » Linter Rules
:description lang=en:
djLint HTML Template linter includes over 30 rules! Find the definitions here.
Easily expand with include custom rules!
:keywords lang=en: template linter, template formatter, djLint, HTML, templates, formatter, linter, rules
Linter Rules
============
Codes
~~~~~
+--------+-------------------------------------------------------------------------+
| Code | Meaning |
+========+=========================================================================+
| T001 | Variables should be wrapped in a single whitespace. Ex: {{ this }} |
+--------+-------------------------------------------------------------------------+
| T002 | Double quotes should be used in tags. Ex {% extends "this.html" %} |
+--------+-------------------------------------------------------------------------+
| T003 | Endblock should have name. Ex: {% endblock body %}. |
+--------+-------------------------------------------------------------------------+
| D004 | (Django) Static urls should follow {% static path/to/file %} pattern. |
+--------+-------------------------------------------------------------------------+
| J004 | (Jinja) Static urls should follow {{ url_for('static'..) }} pattern. |
+--------+-------------------------------------------------------------------------+
| H005 | Html tag should have lang attribute. |
+--------+-------------------------------------------------------------------------+
| H006 | Img tag should have height and width attributes. |
+--------+-------------------------------------------------------------------------+
| H007 | <!DOCTYPE ... > should be present before the html tag. |
+--------+-------------------------------------------------------------------------+
| H008 | Attributes should be double quoted. |
+--------+-------------------------------------------------------------------------+
| H009 | Tag names should be lowercase. |
+--------+-------------------------------------------------------------------------+
| H010 | Attribute names should be lowercase. |
+--------+-------------------------------------------------------------------------+
| H011 | Attribute values should be quoted. |
+--------+-------------------------------------------------------------------------+
| H012 | There should be no spaces around attribute =. |
+--------+-------------------------------------------------------------------------+
| H013 | Img tag should have alt attributes. |
+--------+-------------------------------------------------------------------------+
| H014 | More than 2 blank lines. |
+--------+-------------------------------------------------------------------------+
| H015 | Follow h tags with a line break. |
+--------+-------------------------------------------------------------------------+
| H016 | Missing title tag in html. |
+--------+-------------------------------------------------------------------------+
| H017 | Tag should be self closing. |
+--------+-------------------------------------------------------------------------+
| D018 | (Django) Internal links should use the {% url ... %} pattern. |
+--------+-------------------------------------------------------------------------+
| J018 | (Jinja) Internal links should use the {% url ... %} pattern. |
+--------+-------------------------------------------------------------------------+
| H019 | Replace 'javascript:abc()' with on_ event and real url. |
+--------+-------------------------------------------------------------------------+
| H020 | Empty tag pair found. Consider removing. |
+--------+-------------------------------------------------------------------------+
| H021 | Inline styles should be avoided. |
+--------+-------------------------------------------------------------------------+
| H022 | Use HTTPS for external links. |
+--------+-------------------------------------------------------------------------+
| H023 | Do not use entity references. |
+--------+-------------------------------------------------------------------------+
| H024 | Omit type on scripts and styles. |
+--------+-------------------------------------------------------------------------+
| H025 | Tag seems to be an orphan. |
+--------+-------------------------------------------------------------------------+
| H026 | Emtpy id and class tags can be removed. |
+--------+-------------------------------------------------------------------------+
| T027 | Unclosed string found in template syntax. |
+--------+-------------------------------------------------------------------------+
| T028 | Consider using spaceless tags inside attribute values. {%- if/for -%} |
+--------+-------------------------------------------------------------------------+
| H029 | Consider using lowercase form method values. |
+--------+-------------------------------------------------------------------------+
| H030 | Consider adding a meta description. |
+--------+-------------------------------------------------------------------------+
| H031 | Consider adding meta keywords. |
+--------+-------------------------------------------------------------------------+
+--------+---------------------------------------------------------------------------+
| Code | Meaning |
+========+===========================================================================+
| T001 | Variables should be wrapped in a single whitespace. Ex: ``{{ this }}`` |
+--------+---------------------------------------------------------------------------+
| T002 | Double quotes should be used in tags. Ex ``{% extends "this.html" %}`` |
+--------+---------------------------------------------------------------------------+
| T003 | Endblock should have name. Ex: ``{% endblock body %}``. |
+--------+---------------------------------------------------------------------------+
| D004 | (Django) Static urls should follow ``{% static path/to/file %}`` pattern. |
+--------+---------------------------------------------------------------------------+
| J004 | (Jinja) Static urls should follow ``{{ url_for('static'..) }}`` pattern. |
+--------+---------------------------------------------------------------------------+
| H005 | Html tag should have ``lang`` attribute. |
+--------+---------------------------------------------------------------------------+
| H006 | ``img`` tag should have ``height`` and ``width`` attributes. |
+--------+---------------------------------------------------------------------------+
| H007 | ``<!DOCTYPE ... >`` should be present before the html tag. |
+--------+---------------------------------------------------------------------------+
| H008 | Attributes should be double quoted. |
+--------+---------------------------------------------------------------------------+
| H009 | Tag names should be lowercase. |
+--------+---------------------------------------------------------------------------+
| H010 | Attribute names should be lowercase. |
+--------+---------------------------------------------------------------------------+
| H011 | Attribute values should be quoted. |
+--------+---------------------------------------------------------------------------+
| H012 | There should be no spaces around attribute ``=``. |
+--------+---------------------------------------------------------------------------+
| H013 | ``img`` tag should have alt attributes. |
+--------+---------------------------------------------------------------------------+
| H014 | More than 2 blank lines. |
+--------+---------------------------------------------------------------------------+
| H015 | Follow ``h`` tags with a line break. |
+--------+---------------------------------------------------------------------------+
| H016 | Missing ``title`` tag in html. |
+--------+---------------------------------------------------------------------------+
| H017 | Tag should be self closing. |
+--------+---------------------------------------------------------------------------+
| D018 | (Django) Internal links should use the ``{% url ... %}`` pattern. |
+--------+---------------------------------------------------------------------------+
| J018 | (Jinja) Internal links should use the ``{% url ... %}`` pattern. |
+--------+---------------------------------------------------------------------------+
| H019 | Replace ``javascript:abc()`` with ``on_`` event and real url. |
+--------+---------------------------------------------------------------------------+
| H020 | Empty tag pair found. Consider removing. |
+--------+---------------------------------------------------------------------------+
| H021 | Inline styles should be avoided. |
+--------+---------------------------------------------------------------------------+
| H022 | Use HTTPS for external links. |
+--------+---------------------------------------------------------------------------+
| H023 | Do not use entity references. |
+--------+---------------------------------------------------------------------------+
| H024 | Omit type on scripts and styles. |
+--------+---------------------------------------------------------------------------+
| H025 | Tag seems to be an orphan. |
+--------+---------------------------------------------------------------------------+
| H026 | Emtpy id and class tags can be removed. |
+--------+---------------------------------------------------------------------------+
| T027 | Unclosed string found in template syntax. |
+--------+---------------------------------------------------------------------------+
| T028 | Consider using spaceless tags inside attribute values. ``{%- if/for -%}`` |
+--------+---------------------------------------------------------------------------+
| H029 | Consider using lowercase form method values. |
+--------+---------------------------------------------------------------------------+
| H030 | Consider adding a meta description. |
+--------+---------------------------------------------------------------------------+
| H031 | Consider adding meta keywords. |
+--------+---------------------------------------------------------------------------+
Adding Rules
------------

18
docs/index.rst
View file

@ -1,5 +1,10 @@
.. djlint documentation master file, created by
sphinx-quickstart on Tue Jul 27 15:28:35 2021.
.. meta::
:title lang=en: djLint » HTML Template Linter and Formatter
:description lang=en:
djLint HTML template linter and formatter. Find common syntax errors,
reformat to make your HTML templates shine! Supports django, jinja,
nunjucks, twig, handlebars, mustache, golang, and more!
:keywords lang=en: template linter, template formatter, djLint, HTML, templates, formatter, linter
HTML Template Linter and Formatter
==================================
@ -11,21 +16,20 @@ HTML Template Linter and Formatter
:titlesonly:
Welcome<self>
djlint/usage
djlint/rules
djlint/getting_started
djlint/linter_rules
djlint/formatter
djlint/configuration
djlint/integrations
djlint/best_practices
djlint/changelog
djlint/integrations
.. toctree::
:hidden:
GitHub ↪ <https://github.com/Riverside-Healthcare/djlint>
PyPI ↪ <https://pypi.org/project/djlint/>
Discord ↪ <https://discord.gg/taghAqebzU>
Chat ↪ <https://discord.gg/taghAqebzU>
Find common formatting issues and *reformat* HTML templates.

2
src/djlint/__init__.py
View file

@ -102,7 +102,7 @@ def main(
lint: bool,
use_gitignore: bool,
) -> None:
"""djLint · lint and reformat HTML templates."""
"""djLint · HTML template linter and formatter."""
config = Config(
src[0],
extension=extension,