From 9c4d20e926b44993d8e61fc77cf1107385ef3cd7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mike=20F=C3=A4hrmann?= Date: Fri, 26 Sep 2025 18:47:07 +0200 Subject: [PATCH] [docs/configuration] move notes to definition lists --- docs/configuration.rst | 304 ++++++++++++++++++++--------------------- 1 file changed, 150 insertions(+), 154 deletions(-) diff --git a/docs/configuration.rst b/docs/configuration.rst index a125c3b5..0f3c2db3 100644 --- a/docs/configuration.rst +++ b/docs/configuration.rst @@ -106,8 +106,8 @@ Description 5977527 subcategory image - - Note: Even if the value of the ``extension`` key is missing or +Note + Even if the value of the ``extension`` key is missing or ``None``, it will be filled in later when the file download is starting. This key is therefore always available to provide a valid filename extension. @@ -254,8 +254,8 @@ Default ``"\u0000-\u001f\u007f"`` (ASCII control characters) Description Set of characters to remove from generated path names. - - Note: In a string with 2 or more characters, ``[]^-\`` need to be +Note + In a string with 2 or more characters, ``[]^-\`` need to be escaped with backslashes, e.g. ``"\\[\\]"`` @@ -535,8 +535,8 @@ Description (R) Login with username & password or supplying logged-in `cookies `__ is required - - Note: Leave the ``password`` value empty or undefined +Note + Leave the ``password`` value empty or undefined to be prompted for a password when performing a login (see `getpass() `__). @@ -669,9 +669,8 @@ Description It is also possible to set a proxy for a specific host by using ``scheme://host`` as key. See `Requests' proxy documentation`_ for more details. - - Note: If a proxy URL does not include a scheme, - ``http://`` is assumed. +Note + If a proxy URL does not include a scheme, ``http://`` is assumed. extractor.*.proxy-env @@ -984,8 +983,8 @@ Description * A category or basecategory name (``"imgur"``, ``"mastodon"``) * | A (base)category-subcategory pair, where both names are separated by a colon (``"redgifs:user"``). | Both names can be a `*` or left empty, matching all possible names (``"*:image"``, ``":user"``). - - Note: Any ``blacklist`` setting will automatically include +Note + Any ``blacklist`` setting will automatically include ``"oauth"``, ``"recursive"``, and ``"test"``. @@ -1013,10 +1012,10 @@ Description `PostgreSQL Connection URI `__, the archive will use this PostgreSQL database as backend (requires `Psycopg `__). +Note + Archive files that do not already exist get generated automatically. - Note: Archive files that do not already exist get generated automatically. - - Note: Archive paths support regular `format string`_ replacements, + Archive paths support basic `format string`_ replacements, but be aware that using external inputs for building local paths may pose a security risk. @@ -1325,8 +1324,8 @@ Description | Arguments for range and slice notation are optional and will default to begin (``1``) or end (``sys.maxsize``) if omitted. | For example ``5-``, ``5:``, and ``5::`` all mean "Start at file number 5". - - Note: The index of the first file is ``1``. +Note + The index of the first file is ``1``. extractor.*.chapter-range @@ -1400,8 +1399,8 @@ Description `date-min` and `date-max`. See |strptime|_ for a list of formatting directives. - - Note: Despite its name, this option does **not** control how +Note + Despite its name, this option does **not** control how ``{date}`` metadata fields are formatted. To use a different formatting for those values other than the default ``%Y-%m-%d %H:%M:%S``, put |strptime|_ formatting directives @@ -1956,8 +1955,8 @@ Example * ``["version", "generation"]`` Description Extract additional ``generation``, ``version``, and ``post`` metadata. - - Note: This requires 1 or more additional API requests per image or video. +Note + This requires 1 or more additional API requests per image or video. extractor.civitai.nsfw @@ -1999,8 +1998,8 @@ Description to pass with every image URL. Known available options include ``original``, ``quality``, ``width`` - - Note: Set this option to an arbitrary letter, e.g., ``"w"``, +Note + Set this option to an arbitrary letter, e.g., ``"w"``, to download images in JPEG format at their original resolution. @@ -2073,7 +2072,7 @@ Default Description Password value used to access protected files and folders. - Note: Leave this value empty or undefined + Leave this value empty or undefined to be interactively prompted for a password when needed (see `getpass() `__). @@ -2141,8 +2140,8 @@ Description It is possible to specify a custom list of metadata includes. See `available_includes `__ for possible field names. ``aibooru`` also supports ``ai_metadata``. - - Note: This requires 1 additional HTTP request per 200-post batch. +Note + This requires 1 additional HTTP request per 200-post batch. extractor.[Danbooru].threshold @@ -2156,8 +2155,8 @@ Description Stop paginating over API results if the length of a batch of returned posts is less than the specified number. Defaults to the per-page limit of the current instance, which is 200. - - Note: Changing this setting is normally not necessary. When the value is +Note + Changing this setting is normally not necessary. When the value is greater than the per-page limit, gallery-dl will stop after the first batch. The value cannot be less than 1. @@ -2212,8 +2211,8 @@ Default ``false`` Description Download the avatar of each commenting user. - - Note: Enabling this option also enables deviantart.comments_. +Note + Enabling this option also enables deviantart.comments_. extractor.deviantart.extra @@ -2225,8 +2224,8 @@ Default Description Download extra Sta.sh resources from description texts and journals. - - Note: Enabling this option also enables deviantart.metadata_. +Note + Enabling this option also enables deviantart.metadata_. extractor.deviantart.flat @@ -2244,9 +2243,9 @@ Description favorites-collections and transfer any further work to other extractors (``folder`` or ``collection``), which will then create individual subdirectories for each of them. - - Note: Going through all gallery folders will not be able to - fetch deviations which aren't in any folder. +Note + Going through all gallery folders will not + fetch deviations not contained in any folder. extractor.deviantart.folders @@ -2258,8 +2257,8 @@ Default Description Provide a ``folders`` metadata field that contains the names of all folders a deviation is present in. - - Note: Gathering this information requires a lot of API calls. +Note + Gathering this information requires a lot of API calls. Use with caution. @@ -2344,8 +2343,8 @@ Description Update `JSON Web Tokens `__ (the ``token`` URL parameter) of otherwise non-downloadable, low-resolution images to be able to download them in full resolution. - - Note: No longer functional as of 2023-10-11 +Note + No longer functional as of 2023-10-11 extractor.deviantart.mature @@ -2474,8 +2473,8 @@ Description Using a ``refresh-token`` allows you to access private or otherwise not publicly available deviations. - - Note: The ``refresh-token`` becomes invalid +Note + The ``refresh-token`` becomes invalid `after 3 months `__ or whenever your `cache file `__ is deleted or cleared. @@ -2578,8 +2577,8 @@ Example * ``["notes", "pools"]`` Description Extract additional metadata (notes, pool metadata) if available. - - Note: This requires 0-2 additional HTTP requests per post. +Note + This requires 0-2 additional HTTP requests per post. extractor.[E621].threshold @@ -2593,8 +2592,8 @@ Description Stop paginating over API results if the length of a batch of returned posts is less than the specified number. Defaults to the per-page limit of the current instance, which is 320. - - Note: Changing this setting is normally not necessary. When the value is +Note + Changing this setting is normally not necessary. When the value is greater than the per-page limit, gallery-dl will stop after the first batch. The value cannot be less than 1. @@ -2642,10 +2641,10 @@ Example Description After downloading a gallery, add it to your account's favorites as the given category number. +Note + Set this to `"favdel"` to remove galleries from your favorites. - Note: Set this to `"favdel"` to remove galleries from your favorites. - - Note: This will remove any Favorite Notes when applied + This will remove any Favorite Notes when applied to already favorited galleries. @@ -2796,8 +2795,8 @@ Default ``false`` Description Extract ``comments`` metadata. - - Note: This requires 1 or more additional API requests per post, +Note + This requires 1 or more additional API requests per post, depending on the number of comments. @@ -2825,8 +2824,8 @@ Type Description Do not request API data or extract files from posts that require a fee (``feeRequired``) greater than the specified amount. - - Note: This option has no effect on individual post URLs. +Note + This option has no effect on individual post URLs. extractor.fanbox.metadata @@ -2848,8 +2847,8 @@ Description * ``comments`` * ``plan`` * ``user`` - - Note: ``comments`` can also be enabled via +Note + ``comments`` can also be enabled via `fanbox.comments `__ @@ -2895,8 +2894,8 @@ Default Description For each photo, return the albums and pools it belongs to as ``set`` and ``pool`` metadata. - - Note: This requires 1 additional API call per photo. +Note + This requires 1 additional API call per photo. See `flickr.photos.getAllContexts `__ for details. @@ -2909,8 +2908,8 @@ Default Description For each photo, return its EXIF/TIFF/GPS tags as ``exif`` and ``camera`` metadata. - - Note: This requires 1 additional API call per photo. +Note + This requires 1 additional API call per photo. See `flickr.photos.getExif `__ for details. @@ -2923,8 +2922,8 @@ Default Description For each photo, retrieve its "full" metadata as provided by `flickr.photos.getInfo `__ - - Note: This requires 1 additional API call per photo. +Note + This requires 1 additional API call per photo. extractor.flickr.metadata @@ -2956,8 +2955,8 @@ Default ``false`` Description Extract additional ``user`` profile metadata. - - Note: This requires 1 additional API call per user profile. +Note + This requires 1 additional API call per user profile. See `flickr.people.getInfo `__ for details. @@ -3136,8 +3135,8 @@ Description * Select `Network` -> `XHR` * Open a gallery page * Select the last `Network` entry and copy its ``crt`` value - - Note: You will also need your browser's +Note + You will also need your browser's `user-agent `__ @@ -3359,8 +3358,8 @@ Default Description Provide extended ``user`` metadata even when referring to a user by ID, e.g. ``instagram.com/id:12345678``. - - Note: This metadata is always available when referring to a user by name, +Note + This metadata is always available when referring to a user by name, e.g. ``instagram.com/USERNAME``. @@ -3376,8 +3375,8 @@ Description * ``"asc"``: Same order as displayed in a post * ``"desc"``: Reverse order as displayed in a post * ``"reverse"``: Same as ``"desc"`` - - Note: This option does *not* affect ``{num}``. +Note + This option does *not* affect ``{num}``. To enumerate files in reverse order, use ``count - num + 1``. @@ -3395,8 +3394,8 @@ Description * ``"id"`` or ``"id_asc"``: Ascending order by ID * ``"id_desc"``: Descending order by ID * ``"reverse"``: Same as ``"desc"`` - - Note: This option only affects ``highlights``. +Note + This option only affects ``highlights``. extractor.instagram.previews @@ -3534,8 +3533,8 @@ Default Description Extract additional metadata for ``archives`` files, including ``file``, ``file_list``, and ``password``. - - Note: This requires 1 additional HTTP request per ``archives`` file. +Note + This requires 1 additional HTTP request per ``archives`` file. extractor.kemono.comments @@ -3546,8 +3545,8 @@ Default ``false`` Description Extract ``comments`` metadata. - - Note: This requires 1 additional HTTP request per post. +Note + This requires 1 additional HTTP request per post. extractor.kemono.duplicates @@ -3664,8 +3663,8 @@ Description Extract post revisions. Set this to ``"unique"`` to filter out duplicate revisions. - - Note: This requires 1 additional HTTP request per post. +Note + This requires 1 additional HTTP request per post. extractor.kemono.order-revisions @@ -3843,11 +3842,9 @@ Default Description The ``access-token`` value you get from `linking your account to gallery-dl `__. - - Note: gallery-dl comes with built-in tokens for ``mastodon.social``, - ``pawoo`` and ``baraag``. For other instances, you need to obtain an - ``access-token`` in order to use usernames in place of numerical - user IDs. +Note + gallery-dl comes with built-in tokens for + ``mastodon.social``, ``pawoo``, and ``baraag``. extractor.[mastodon].cards @@ -3949,8 +3946,8 @@ Default ``false`` Description Extract extended ``pool`` metadata. - - Note: Not supported by all ``moebooru`` instances. +Note + Not supported by all ``moebooru`` instances. extractor.naver-blog.videos @@ -4119,8 +4116,8 @@ Default ``6414`` Description Port number to listen on during OAuth authorization. - - Note: All redirects will go to port ``6414``, regardless +Note + All redirects will go to port ``6414``, regardless of the port specified here. You'll have to manually adjust the port number in your browser's address bar when using a different port than the default. @@ -4134,8 +4131,8 @@ Default ``false`` Description Extract additional metadata (``source``, ``uploader``) - - Note: This requires 1 additional HTTP request per post. +Note + This requires 1 additional HTTP request per post. extractor.patreon.cursor @@ -4402,8 +4399,8 @@ Description For works bookmarked by `your own account `__, fetch bookmark tags as ``tags_bookmark`` metadata. - - Note: This requires 1 additional API request per bookmarked post. +Note + This requires 1 additional API request per bookmarked post. extractor.pixiv.captions @@ -4425,8 +4422,8 @@ Default ``false`` Description Fetch ``comments`` metadata. - - Note: This requires 1 or more additional API requests per post, +Note + This requires 1 or more additional API requests per post, depending on the number of comments. @@ -4505,8 +4502,8 @@ Default ``false`` Description Fetch ``comments`` metadata. - - Note: This requires 1 or more additional API requests per novel, +Note + This requires 1 or more additional API requests per novel, depending on the number of comments. @@ -4574,8 +4571,8 @@ Description For novels bookmarked by `your own account `__, fetch bookmark tags as ``tags_bookmark`` metadata. - - Note: This requires 1 additional API request per bookmarked post. +Note + This requires 1 additional API request per bookmarked post. extractor.pixiv-novel.refresh-token @@ -4718,8 +4715,8 @@ Default Description Retrieve additional comments by resolving the ``more`` comment stubs in the base comment tree. - - Note: This requires 1 additional API call for every 100 extra comments. +Note + This requires 1 additional API call for every 100 extra comments. extractor.reddit.embeds @@ -4984,8 +4981,8 @@ Description * Select `Network` -> `XHR` * Open a gallery page * Select the last `Network` entry and copy its ``crt`` value - - Note: You will also need your browser's +Note + You will also need your browser's `user-agent `__ @@ -5733,8 +5730,8 @@ Description as running ``gallery-dl https://twitter.com/i/web/status/`` with enabled `conversations `__ option for each Tweet in said timeline. - - Note: This requires at least 1 additional API call per initial Tweet. +Note + This requires at least 1 additional API call per initial Tweet. extractor.twitter.unavailable @@ -5907,8 +5904,8 @@ Description If this value is ``"self"``, only consider replies where reply and original Tweet are from the same user. - - Note: Twitter will automatically expand conversations if you +Note + Twitter will automatically expand conversations if you use the ``/with_replies`` timeline while logged in. For example, media from Tweets which the user replied to will also be downloaded. @@ -6049,8 +6046,8 @@ Description * ``"timeline"``: ``https://twitter.com/id:{rest_id}/timeline`` * ``"tweets"``: ``https://twitter.com/id:{rest_id}/tweets`` * ``"media"``: ``https://twitter.com/id:{rest_id}/media`` - - Note: To allow gallery-dl to follow custom URL formats, set the blacklist__ +Note + To allow gallery-dl to follow custom URL formats, set the blacklist__ for ``twitter`` to a non-default value, e.g. an empty string ``""``. .. __: `extractor.*.blacklist & .whitelist`_ @@ -6104,8 +6101,8 @@ Default ``false`` Description Automatically `like` posts after downloading their images. - - Note: Requires `login `__ +Note + Requires `login `__ or `cookies `__ @@ -6209,8 +6206,8 @@ Default ``false`` Description Extract additional metadata (tags, uploader) - - Note: This requires 1 additional HTTP request per post. +Note + This requires 1 additional HTTP request per post. extractor.weasyl.api-key @@ -6234,8 +6231,8 @@ Description | Fetch extra submission metadata during gallery downloads. | (``comments``, ``description``, ``favorites``, ``folder_name``, ``tags``, ``views``) - - Note: This requires 1 additional HTTP request per submission. +Note + This requires 1 additional HTTP request per submission. extractor.webtoons.quality @@ -6487,8 +6484,8 @@ Default Description Route |ytdl's| output through gallery-dl's logging system. Otherwise it will be written directly to stdout/stderr. - - Note: Set ``quiet`` and ``no_warnings`` in +Note + Set ``quiet`` and ``no_warnings`` in `extractor.ytdl.raw-options`_ to ``true`` to suppress all output. @@ -6553,8 +6550,8 @@ Default ``false`` Description Extract additional metadata (date, md5, tags, ...) - - Note: This requires 1-2 additional HTTP requests per post. +Note + This requires 1-2 additional HTTP requests per post. extractor.zerochan.pagination @@ -6592,8 +6589,8 @@ Description Group ``tags`` by type and provide them as ``tags_`` metadata fields, for example ``tags_artist`` or ``tags_character``. - - Note: This requires 1 additional HTTP request per post. +Note + This requires 1 additional HTTP request per post. extractor.[booru].notes @@ -6604,8 +6601,8 @@ Default ``false`` Description Extract overlay notes (position and text). - - Note: This requires 1 additional HTTP request per post. +Note + This requires 1 additional HTTP request per post. extractor.[booru].url @@ -6890,8 +6887,8 @@ Default Description Number of seconds to sleep when receiving a `429 Too Many Requests` response before `retrying `__ the request. - - Note: Requires +Note + Requires `retry-codes `__ to include ``429``. @@ -6996,8 +6993,8 @@ Default Description Route |ytdl's| output through gallery-dl's logging system. Otherwise it will be written directly to stdout/stderr. - - Note: Set ``quiet`` and ``no_warnings`` in +Note + Set ``quiet`` and ``no_warnings`` in `downloader.ytdl.raw-options`_ to ``true`` to suppress all output. @@ -7038,8 +7035,8 @@ Description * ``"default"``: use |ytdl's| default, currently ``"%(title)s [%(id)s].%(ext)s"`` for yt-dlp_ / ``"%(title)s-%(id)s.%(ext)s"`` for youtube-dl_ - - Note: An output template other than ``null`` might +Note + An output template other than ``null`` might cause unexpected results in combination with certain options (e.g. ``"skip": "enumerate"``) @@ -7159,8 +7156,8 @@ Description When this option is specified as a simple ``string``, it is interpreted as ``{"encoding": "", "errors": "replace"}`` - - Note: ``errors`` always defaults to ``"replace"`` +Note + ``errors`` always defaults to ``"replace"`` output.shorten @@ -7714,8 +7711,8 @@ Example Description Custom format string to build filename extensions for metadata files with, which will replace the original filename extensions. - - Note: `metadata.extension`_ is ignored if this option is set. +Note + When this option is set, `metadata.extension`_ is ignored. metadata.metadata-path @@ -7782,8 +7779,8 @@ Example ``["id", "width", "height", "description"]`` Description Include only the given top-level keys when writing JSON data. - - Note: Missing or undefined fields will be silently ignored. +Note + Missing or undefined fields will be silently ignored. metadata.exclude @@ -7794,8 +7791,8 @@ Example ``["blocked", "watching", "status"]`` Description Exclude all given keys from written JSON data. - - Note: Cannot be used with `metadata.include`_. +Note + Cannot be used with `metadata.include`_. metadata.fields @@ -7834,8 +7831,8 @@ Example * ``["tags:", "", "{tags:J\n}"]`` Description Custom format string to build the content of metadata files with. - - Note: Only applies for ``"mode": "custom"``. +Note + Only applies to ``"mode": "custom"``. metadata.ascii @@ -7848,8 +7845,8 @@ Description Escape all non-ASCII characters. See the ``ensure_ascii`` argument of |json.dump()|_ for further details. - - Note: Only applies for ``"mode": "json"`` and ``"jsonl"``. +Note + Only applies to ``"mode": "json"`` and ``"jsonl"``. metadata.indent @@ -7863,8 +7860,8 @@ Description Indentation level of JSON output. See the ``indent`` argument of |json.dump()|_ for further details. - - Note: Only applies for ``"mode": "json"``. +Note + Only applies to ``"mode": "json"``. metadata.separators @@ -7878,8 +7875,8 @@ Description to separate JSON keys and values with. See the ``separators`` argument of |json.dump()|_ for further details. - - Note: Only applies for ``"mode": "json"`` and ``"jsonl"``. +Note + Only applies to ``"mode": "json"`` and ``"jsonl"``. metadata.sort @@ -7892,8 +7889,8 @@ Description Sort output by `key`. See the ``sort_keys`` argument of |json.dump()|_ for further details. - - Note: Only applies for ``"mode": "json"`` and ``"jsonl"``. +Note + Only applies to ``"mode": "json"`` and ``"jsonl"``. metadata.open @@ -8007,8 +8004,8 @@ Description This value must be either a UNIX timestamp or a |datetime|_ object. - - Note: This option gets ignored if `mtime.value`_ is set. +Note + This option is ignored if `mtime.value`_ is set. mtime.value @@ -8069,9 +8066,8 @@ Description `Python expression `__ to `evaluate `__. - - Note: Only used with - `"mode": "eval" `__ +Note + Only used with `"mode": "eval" `__ python.function @@ -8350,8 +8346,8 @@ Example ``["info.json"]`` Description List of extra files to be added to a ZIP archive. - - Note: Relative paths are relative to the current +Note + Relative paths are relative to the current `download directory `__. @@ -8415,8 +8411,8 @@ Description gets `imported `__ and searched for potential extractors, i.e. classes with a ``pattern`` attribute. - - Note: ``null`` references internal extractors defined in +Note + ``null`` references internal extractors defined in `extractor/__init__.py `__ or by `extractor.modules`_. @@ -8883,7 +8879,7 @@ Description Simple `tilde expansion `__ and `environment variable expansion `__ is supported. -Note: +Note In Windows environments, both backslashes ``\`` as well as forward slashes ``/`` can be used as path separators. @@ -8959,8 +8955,8 @@ Description * encoding * File encoding * Default: ``"utf-8"`` - - Note: path, mode, and encoding are only applied when configuring +Note + path, mode, and encoding are only applied when configuring logging output to a file.