Listing specific documents by category, tag, and more
Document Library Pro will list all documents on your document library page - either as a single list, or structured into category-based folders. You can also use the [doc_library] shortcode to list specific documents only. This page describes the shortcode options which you can choose to control which documents are listed in each library on your site.
You can list documents with a specific category, tag, status, custom taxonomy term, custom field or date (year, month or day). You can also show or hide specific documents based on their ID, and exclude certain categories.
Document category
The doc_category option lets you choose which documents are listed.
You should specify the category slug or ID – this can be found under the Documents → Categories menu in the WordPress dashboard. You can also specify multiple categories to display – either separated by commas or by a plus sign (+). If you use commas it means “documents in this Category A or Category B”. If you use a plus, it means “documents in Category A and Category B”.
For example, to display documents which are in the “design” category or in the “print” category, use: [doc_library doc_category="design,print"]
To display documents which are in the “design” category and in the “print” category, use: [doc_library doc_category="design+print"]
Can I list categories and sub-categories separately?
The default shortcode displays documents in a single list, regardless of whether they are in a parent category or child category. You can enable the folders option to structure the document into nested folders based on their categories and sub-categories.
Alternatively, you can manually list documents as categories and sub-categories by adding multiple shortcodes to the page. Each shortcode should list documents from a different category or subcategory, and you can divide up the page by adding the category name as a subheading above each list. For example, this will be useful if you want all your lists of documents to be visible without having to click on a folder to open them one at a time; or if you're using a page builder plugin to structure your page into tabs, toggles or accordions and want to list documents from a different category in each section.
Document tag
The doc_tag option selects documents based on their document library tags. If you’re displaying pages or other custom post types, this option has no effect and you need to use the ‘term‘ option instead (see below).
Use the tag slug or tag ID – you can find this in WordPress under the Documents → Tags menu.
As with categories, you can use one tag or several tags, and you can use commas or a plus sign to denote how tags should be checked. Using commas means “documents with this tag OR that tag”; using the plus sign (+) means “documents with this tag AND that tag”. You can’t mix and match commas and pluses – it’s one or the other.
Example 1: Display documents with tag “awesome”: [doc_library doc_tag="awesome"][/no_shortcodes]
Example 2: Display documents with tags “cool”, “awesome” or “good”: [no_shortcodes][doc_library doc_tag="cool,awesome,good"]
Example 3: documents with tags “cool”, “awesome” and “good”: [doc_library doc_tag="cool+awesome+good"]
Custom taxonomy term
The term option lists documents with the specified term or terms.
Use the format: term="<taxonomy slug>:<term slug or ID>". You can enter one term or multiple terms and, as with categories and tags, you can separate terms using a comma (,) or a plus sign (+) to denote whether the documents have any of the terms specified or all of them.
You need to prefix this option with the slug of the taxonomy followed by a colon. For example, to display documents that are tagged with the year “2021”, we would use:
[doc_library columns="title,content" term="year:2021"]
To display documents with multiple terms, separate terms by a plus sign (AND) or a comma (OR). If you are selecting from several custom taxonomies, you need to add the taxonomy slug before each term.
The following example will display documents with a document_type of policy or memo:
[doc_library term="document_type:policy,memo"]
The following example will display documents with a document_type of memo and a document_status of approved:
[doc_library term="document_type:policy+document_status:approved"]
If you haven't created your custom taxonomies yet, check out our article on how to do this.
Custom field
The cf option is used to select documents based on a custom field value. You should use the format cf="<field name>:<field value>" when using this option. As with the above options you can enter one custom field to check, or several, and can separate them using a comma or a plus sign (see categories or tags for more details).
For example, if you wanted to display the documents for cars which are either blue OR are Audis, you would use:
[doc_library cf="color:blue,make:audi"]
If you wanted to list documents with either of two values from the same custom field (for example cars that are blue or red) then you would use:
[doc_library cf="color:blue,color:red"]
However if you wanted to select the blue Audis (i.e. have color = blue AND make = audi) you would use:
[doc_library cf="color:blue+make:audi"]
If you haven't created your custom taxonomies yet, check out our tutorial on how to do this.
Custom fields added using the Toolset plugin
If you're using Toolset to create your custom fields, then you need slightly different syntax to display them in the document library.
Toolset adds wpcf- to the start of the custom field name, so if you create a custom field called 'color' with a value of 'blue' then the correct syntax will be wpcf-color:blue. This means that if you want to list documents with a custom field value of 'blue' then you would need to add it as follows:
[doc_library cf="cf:wpcf-color:blue"]
Status
The status option displays documents based on their status.
The default status is publish. The other options are draft, pending, future, private or any. Pending documents are those pending a review. Future documents are those scheduled to be published at a future date. Private documents have their visibility set to Private which means they can only be viewed by users with an administrator or editor role.
You can also use a list of document statuses separated by commas, for example:
[doc_library status="publish,draft"]
See also: How to automatically expire documents and remove them from the library on a certain date.
Display documents based on when they were published
The following three options control which documents are displayed based on the date they were published.
Please note that these options use the year when you published the document post on your website, which may be different from when your organization published the document internally (for example). You can change the publish date for each document, either by using 'Quick Edit' on the main list of documents; or in the 'Publish' section in the top right corner of the 'Edit Document' screen.
Year
The year option can be set to limit documents to a specific year. E.g.[doc_library year="2021"]
Month
Selects documents from a specific month. You should use a number here between 1 and 12. You can combine this with the year or day options if you want more fine-grained control, e.g. [doc_library year="2021" month="11"]
Day
Selects documents from a specific day in the month. You should use a number between 1 and 31, and as above, you can combine this with the year or month options, e.g.[doc_library month="4" day="25"]
Document author
The document_author displays the documents written/published by a specific author. You need to select the author from the list adding the document. You can change the document author by editing that specific document.
If you can't find the author, you might need to add the author first. You can do this by going to Documents → Authors, entering the author name, slug, description, and clicking on the Add New Author button.
Example: [doc_library document_author="sarah"]
Note: It is also possible to display documents which were added by specific WordPress users.
Exclude
The exclude option can be used to exclude documents from your library based on their database ID. You can enter one ID or a list or IDs.
Example: [doc_library columns="title,content" post_type="page" exclude="23"]
Include
The include option can be used to show only specific documents. You can enter one post ID or a list or IDs separated by commas. Note that include and exclude are mutually exclusive – if you set one, the other will be ignored.
Example displaying 4 specific documents: [doc_library include="23,45,67,90"]
Exclude document category
The exclude_doc_category option is used to exclude entire categories of documents. You can use category IDs or slugs, and it can be one category or a comma-separated list.
Example: [doc_library exclude_doc_category="3,6"]
Example: [doc_library exclude_doc_category="design"]
Exclude taxonomy term
The exclude_term option is used to exclude documents with a specific taxonomy term. You can use taxonomy term IDs or slugs, and it can be one category or a comma-separated list.
Example: [doc_library exclude_term="label:staff"]
Example: [doc_library exclude_term="label:3,6"]
Example: [doc_library exclude_term="label:staff,region:devon"]