☝️ Help for Pwic.wiki (in English only)

Matrix of the authorizations

Setup the server✔️
Create a backup✔️ (console)
Create a project✔️ (console)
Take over a project✔️ (console)
Split a project✔️ (console)
Delete a project✔️ (console)
Create a user account✔️
Change the own password✔️✔️✔️✔️✔️
Change the password of another user✔️ (console)
Grant the authorizations✔️
Create a page✔️
Modify a page✔️✔️
Move a page✔️
Delete a page✔️ (partial)✔️ (partial)✔️ (partial)
Read a page✔️✔️✔️✔️✔️
View the history of a page✔️✔️✔️✔️✔️
Export a page✔️ (partial)✔️ (partial)✔️ (partial)✔️ (partial)✔️ (partial)
Validate a revision✔️
Export a project✔️
Verify the links✔️
Graph of the links✔️
Search across the pages✔️✔️✔️✔️✔️
Search across the documents✔️✔️✔️✔️✔️
View the activity log✔️
View the activity of a user✔️✔️✔️✔️✔️
Automate Pwic.wiki (API)✔️ (partial)✔️ (partial)✔️ (partial)✔️ (partial)✔️ (partial)
Report into BI (OData)✔️✔️ (partial)✔️ (partial)✔️ (partial)✔️ (partial)
Read the licences✔️

☝️ Setup the server

Refer to the file README.md available at the root directory of the application to know more about the default setup.

Running commands

By design, the most important configuration cannot be done online, so you will have to invoke the administration console. Execute the command python3 pwic_admin.py [arguments] under Linux or python pwic_admin.py [arguments] under Windows.

To simplify this syntax, just type ./pa [arguments] under Linux or pa.bat [arguments] under Windows. By convenience, the long syntax for Linux is used below.

Initialize the database

The initialization consists in creating the SQLite database and the folders that store the uploaded files. It is done once at the beginning with the command python3 pwic_admin.py init-db.

In rare cases if the Python code fails for example, the database can be locked without timeout. In this case, try first to run the command python3 pwic_admin.py unlock-db else restart the server.

Set the parameters

With the command python3 pwic_admin.py set-env --help, you can define the following parameters that will change Pwic.wiki's behavior.

The project-dependent variables are mostly changeable online in the special page, but not all for security reasons. The project-independent variables generally can be edited through the console only and it often requires the restart of the server. The users will then have to reconnect from another tab, unless you define the option keep_sessions.

Name Project-dependent Changeable online Description
api_cors Enable CORS for the API from the origins separated by a space listed in this option (example: http://site1.tld https://site2.tld). The value * allows all the origins.
api_expose_markdown Expose the content of the pages in the API /api/project/get to allow the full copy of the documentation.
audit_range Number of days in the past for the online visibility of the audit data that are restricted to the administrators. Define the value -1 to switch off the listing. The archived audit data are not visible online.
auto_join Any user is granted as a reader depending on the value of the option:
- active: automatically when the user connects to Pwic.wiki,
- sso: same as active for the federated authentication only,
- passive: when the user opens the project on purpose.
You can add any user manually at any time. To exclude a user alongside with the automatic join, simply disable (not remove) the user from the management screen of the users. The option is useful when you need a public workspace for your team members but you don't want to manage the initial access manually. The option must be defined by project, not globally.
base_url Define the base HTTP(S) address of your website so that the links can be rebuilt correctly when some data are exported. Don't write the trailing character /. Restart the server after the option is set. Verify the option https.
client_size_max If you handle pages larger than 1 MB, you should enlarge the quantity of data that you can submit by HTTP request else you receive the error 413 Request entity too large. This setting must be configured as well in your reverse proxy server (if you have one).
compressed_cache If the option no_cache is disabled, you have the choice to compress the HTML cache of the pages to save some disk space in the database, but a little CPU effort is required to decompress all the output pages. Restart the server after the option is modified and clear the cache the use the new option.
css Define absolute or relative HTTP locations for additional CSS files separated by ;. This applies as a default theme.
css_dark Define absolute or relative HTTP locations for additional CSS files separated by ;. This applies as an overlay of the default theme and if dark_theme is activated.
css_printing Define absolute or relative HTTP locations for additional CSS files separated by ;. This applies as an overlay of the default theme (the dark theme doesn't apply here) when the user prints the page. This option has no effect on no_printing.
dark_theme Enable the dark mode that is less aggressive in terms of brightness.
db_async Disable the synchronous commit logic of the database to increase significantly its speed. The increased risk to lose data is the compensation. Restart the server after the option is modified.
document_name_regex Set a regular expression to force any uploaded files to respect a strict naming convention. For example, you can use the pattern \.(7z|gz|zip)$ to allow some file extensions only. The file names are always checked in lower case.
document_pixels_max Define the maximal number of pixels (simple multiplication of the width by the height) for an uploaded picture. For information, a standard screenshot is around 2 millions pixels.
document_size_max All the uploaded files must have a size in bytes lower or equal than this limit. Set the value 0 to disable the upload of the files.
edit_time_min Apply a minimum number of seconds between two edits. This limit does not apply to the managers.
emojis List of emojis that can be suggested when you edit a page. They are written in hexadecimal notation and separated by a space. For example, 2705 274C 2754 will propose ✅ ❌ ❔. Many websites can help you to identify the Unicode symbols. If the option has the value *, all the default emojis are loaded.
export_project_revisions Include all the revisions of the pages when you export a project as a ZIP file. It increases the memory footprint.
feed_size Maximal number of entries in the ATOM and RSS feeds.
file_formats_disabled List of the file extensions separated with a space that cannot be used to export a page. The value * disables all the formats.
fixed_templates The layout of the website is loaded once. This option is recommended in your productive environment to increase the performances. You must restart Pwic.wiki after an update is applied to the source code.
heading_mask Codify the headers according to the given format. The default one is There are 6 levels maximum. You can use the Arabic numerals (1), the Roman notation up to 4999 in uppercase (I) or in lowercase (i), a letter in uppercase (A) or in lowercase (a). The separator is a free character. For example, you can define A)1)a-a.1.a.. The implicit tag name for the header is named with #p followed by the shortest codification, in lowercase and with an underscore (ex: #pi_1_a_a).
http_log_file - Define the absolute or relative file name to log passively all the HTTP requests. There is no log file when the option is empty.
- The option is effective upon the restart of the server.
- Because the log file is exclusively locked, you must terminate Pwic.wiki before you can rotate the logs with the command python3 pwic_admin.py rotate-logs.
- The log file includes neither user names, nor processed data. It should not be mistaken with the internal audit tables that are updated by name when a relevant write operation occurs in the database.
http_log_format The format of the HTTP log file can be modified according to this specification.
http_referer Enable the check on the HTTP referer for the POST requests (that is for the API) in regards of the option base_url that must be defined. This security feature is not reliable and old-fashioned. The option does not apply on the static files. Restart the server after the option is set.
https Enable HTTPS provided that you have installed or generated the appropriate certificates. The new value is effective after the restart of the server.
ip_filter List of IP addresses or IP networks separated by a space. The unauthorized addresses are prefixed by the tilde character ~ and used as AND conditions. The authorized addresses are OR conditions and must be true at least once. Use the prefix # to ignore a value. The IP address used for the check is deducted from the HTTP headers through a custom code. The option does not affect the static files. You need to restart the server to consider the made changes.
kbid Self-managed counter on 6 figures to allocate an identifier to a knowledge base article. If you need to change the length of the key, you must edit kb_mask in the source code directly when Pwic.wiki is installed.
keep_drafts By default, the drafts are considered as a work in progress, so they are not important milestones for the traceability of the documentation. This option prevents the automatic deletion of the own drafts when a final page is saved. The drafts remain deletable manually.
keep_sessions The session of a user is saved in a client-side encrypted cookie, so nobody can change its values. This option prevents the internal cryptographic key from being regenerated when the server starts. The effects are:
- The sessions of the users are never terminated, unless they expire after some time due to the option session_expiry or you restart Pwic.wiki with the command line option --new-session.
- While they are writing, the users don't have to reconnect in another tab after the server is restarted, but the session expiry is still applicable.
- The following message disappear from the console: "Cannot decrypt cookie value, create a new fresh session".
Warning: the cryptographic key is stored in the database when the option is enabled. Leaking its value may compromise the data stored in the database.
language Language code used on the project on 2 characters that follows the codification ISO 639-1. If the value is not specified, the language of the connection is used.
legal_notice A legal text can be displayed at the bottom of the pages.
link_new_tab The external links will open in a new tab. You don't need to regenerate the cache after the value is changed because the option is dynamic client-side.
link_nofollow The external links marked as rel="nofollow" don't contribute to the search engine optimization (SEO). The option applies server-side on the dynamic content only, so the cache must be regenerated if it is changed. This option is not recommended by default.
magic_bytes Pwic.wiki has a predefined list of usual file types and their signature. This security feature ensures that a file has the expected extension of its first bytes. Your local mimes can be listed by running the command python pwic_admin.py show-mime (under Windows only).
maintenance The value is displayed on the pages to inform the users of a planned maintenance. The upload and the deletion of the documents are immediately disabled.
mathjax Enable the renderer of mathematical expressions. As a special constraints, the sign \ must be doubled. For example, the usual form \(\sqrt{x^2}\) should be written as \\(\\sqrt{x^2}\\) in the online editor.
mde Enable the wysiwyg Markdown editor.
message Show an online message for informational purposes only. No HTML is allowed.
no_cache Disable the caching of the pages for debugging purposes. When the option is enabled, the existing cache can be cleared from the administration console only.
no_copy_code Disable the one-click copy of the source code rendered in the pages. The option does not react to the option no_text_selection.
no_document_conversion Disable the possibility to convert an attached document from OpenDocument/HTML to Markdown.
no_export_project Disable the export of the project as an archive for the online administrators.
no_feed Disable the ATOM and RSS feeds.
no_graph Disable the ability to render the pages of the project in a graph.
no_heading Hide the automatic codification of the headers. The option heading_mask is still applicable for the internal naming of the paragraphs, so that you can link directly to them. The option has no effect on the export to OpenDocument.
no_help Hide the current help from the footer but the page remains accessible by direct access.
no_highlight Disable the highlight of the source codes. Restart the server after the option is modified. The dependent Python package pygments is optional during the setup.
no_history Disable the ability to see the revisions of a page (a fortiori to access one of its revisions explicitly) when the user is a pure reader. In other words, the pure readers only see the latest revision, or the latest validated revision if the option validated_only is used too.
no_link_review Disable the ability to check the broken and orphaned links of a project.
no_login - Skip the login screen and assign the anonymous role to your visitors.
- On contrary to the option auto_join, they don't need a user account to read the pages.
- You can hide a project by disabling the user account pwic_anonymous.
- The option robots is recommended when the option is turned on.
no_new_user When the option is enabled, you can assign only existing user accounts to your project. To create a new user account, use the administration console of Pwic.wiki. The option has no effect on the federated authentication.
no_printing To save some trees, enable a basic protection to prevent the printing of a page. It also disables the export to PDF through a virtual printer.
no_search Disable the search engine and the search link that you can add to your browser.
no_sort_table Disable the ability to sort the tables by clicking on their header line.
no_space_page When a page is created or moved, the option replaces the spaces in its name by an underscore (_).
no_text_selection Enable a basic protection to prevent the user from playing around with his web browser to copy the text of the main page. It also forces the readers to focus on reading the page.
odata Enable the OData service to report Pwic.wiki into your favorite BI system.
odt_image_height_max Maximal height of the pictures exported to OpenDocument expressed in unit cm, in, mm, pc, pt or px. The value 600px is used by default.
odt_image_width_max Maximal width of the pictures exported to OpenDocument expressed in unit cm, in, mm, pc, pt or px. The value 900px is used by default.
odt_page_height Height of the paper when you export a page to OpenDocument and expressed in unit cm, in, mm, pc, pt or px. The value 29.7cm is used by default (format A4).
odt_page_landscape With this option, the page layout is landscape when you export a page to OpenDocument. By default, the portrait layout is used.
odt_page_margin Size of the borders of the paper exported to OpenDocument. The value should be expressed in unit cm, in, mm, pc, pt or px. The default value 2.5cm (~1 in) is used by convenience.
odt_page_width Width of the paper when you export a page to OpenDocument and expressed in unit cm, in, mm, pc, pt or px. The value 21cm is used by default (format A4).
page_count_max Maximal number of pages that can be defined per project.
password_regex Set a regular expression to force the passwords to respect a predefined format. Few examples can be found here. The option does not apply when you reset the password from the console.
project_size_max Define the maximal disk space in bytes allowed for all the attached documents of a project.
pwic_audit_id This option is automatically set in the backup databases only to identify the last known event of the audit log. In case you need to restore the database, you can clean and reuse the existing audit table. The option is used for internal purposes and it cannot be managed manually.
pwic_session Non-changeable and private key for the handling of the sessions. Refer to keep_sessions for more details. The value must never be disclosed.
quick_fix Under some conditions, a new revision is not created if the content of the page is not changed. A manager can then fix the attributes of a page quickly on behalf of the original author of the latest revision.
registration_link HTTP link to request your access to the website. You cannot register yourself.
revision_count_max Maximal number of revisions that can be defined per page. The deleted revisions don't matter for the total.
revision_size_max Maximal number of characters per revision. If needed, adjust the option client_size_max accordingly.
robots - The meta information robots impacts the search engine optimization (SEO) of your projects in case it is made public through the option no_login.
- The parameter is optionally considered by the crawler. Several values separated with a space are available: archive, noarchive, follow, nofollow, index, noindex, snippet and nosnippet.
- Refer also to the related option seo_hide_revs.
- The values are overridden for some specific pages.
rstrip Remove the trailing space characters when a page is saved.
seo_hide_revs The old revisions of a page are automatically marked as non-indexable for the public search engines. This dynamic rule overrides some values defined in the option robots. The option is incompatible with validated_only.
session_expiry Number of seconds after which a user is automatically disconnected. Don't use a too small value. When a user edits a page, Pwic.wiki warns if the session is lost to not waste the work in progress. The option is effective upon the restart of the server.
show_members_max Reduce the display of the members in the special page if their number is greater than the value of this option. Indeed, the list can be big in large organizations. Only the lists of readers and editors are reduced, so that you can always contact the deciders.
skipped_tags Specify the list of additional HTML elements separated by a space that must be removed during the rendering of the pages. This filter applies to the export to OpenDocument too. Some tags are mandatorily removed for security reasons. You should regenerate the cache if you make the option more permissive.
strict_cookies Enable the strict SameSite for the cookies, but the federated authentication cannot be used anymore. Restart the server after the option is set.
support_email A user can write to this email address to get support.
support_phone A user can call this phone number to get support.
support_text Free text to describe how to get in touch with the support team. You cannot use HTML.
support_url Portal address that a user can use to find an extended help.
title Suffix appended to the title of the pages that can be used to name the website.
validated_only Force the default redirection of the pure readers to the last validated revision of a page if it exists. This feature allows the editors to prepare the upcoming revisions of a page without showing them by default, and to publish only validated pages to the end-users. As a complement, use the option no_history to hide the history of the page.
zip_no_exec Forbid the upload of ZIP files that contain an executable content.

To show one or all the parameters, use the command python3 pwic_admin.py show-env.

In case you need to clean the obsolete variables, run the command python3 pwic_admin.py repair-env. This could happen after Pwic.wiki is upgraded.

Federated authentication

You can connect to Pwic.wiki by using a professional third-party identity provider. The mecanism OAuth relies on secret keys and, obviously, a lot of trust. The user connects from another website and Pwic.wiki pings back the server to fetch the main email address of the user. The account is then automatically configured by default. No other personal information are used.

Several project-independent variables must be defined in the following order. Any change requires the restart of the server.

Name Description github google microsoft
base_url Refer above.
oauth_provider Name of the third-party identity provider:
- github (documentation)
- google (documentation)
- microsoft (documentation)
- No value means that the feature is disabled
oauth_tenant The tenant identifies your organization.
oauth_identifier Unique identifier of the application as declared in the third-party identity provider.
oauth_secret Secret password to connect to the third-party identity provider. The saved value is protected in Pwic.wiki against its public exposure.
oauth_domains List of the authorized domains for the email of the user, separated by a space and ordered by descending priority. Optional Optional Optional
strict_cookies Remove this option.

Reverse proxy

The feature is supported but not enabled by default because the filter by IP address should not be sensible to some special HTTP headers.

By using Nginx or Apache, you need to modify the code of the extension named on_ip_header and to configure the format of the HTTP log.

Compress the static files

Optionally, if you use mobile devices, it is possible to compress the big static files with the command python3 pwic_admin.py compress-static. This will reduce a bit the bandwidth and the loading time.

The option must be configured as well in your reverse proxy server (if you use one).

SQL queries

To facilitate the maintenance of the database remotely, the command python3 pwic_admin.py execute-sql allows you to execute online SQL statements in the console. It is very useful to upgrade Pwic.wiki and perform special operations.

☝️ Create a backup

First, it is recommended to warn your users in advance through the option maintenance. Note that it disables the capability to attach or update new documents to the pages.

At the time of the maintenance, shut down the server with python3 pwic_admin.py shutdown-server, and run the command python3 pwic_admin.py create-backup. A new file is created with the current time stamp. The name of the backup file can be extracted with sed if you have further scripting needs. Basically, it is a copy of the database without the documents that remain in the dedicated folder of the projects.

To restore the backup, simply replace the current database with a previous backup. Any changes made meanwhile will be lost. You must also ensure that the backup file is compatible with your used version of Pwic.wiki and that the salt PWIC_SALT is the same. To resynchronize the documents with the database and vice versa, run the command python3 pwic_admin.py repair-documents --test from the console.

As an alternative, you can backup the entire folder db/ with your own administration tools.

☝️ Create a project

As per the authorizations are designed, the creation of a new project is only possible in command line. Run the command python3 pwic_admin.py create-project --help for further details.

By default, you cannot create new pages. You must extend your rights as a manager, or add new dedicated users having that profile. Refer to the matrix above for the feasible actions per profile.

To show the existing projects and their ownership, run the command: python3 pwic_admin.py show-projects.

☝️ Take over a project

A project can become orphaned if the unique administrator left or is disabled. In this case, it is not possible to assign a new role online.

Run the command python3 pwic_admin.py takeover-project --help for further details.

When you revoke a user, you are warned if a project will be orphaned.

☝️ Split a project

The operation consists in copying one or several projects into a separate database file. The copied projects are not removed from the original database. The audit log stored in its dedicated database and the documents stored on the drive are not modified.

After you copied the databases and the documents to the target server, you can clean the audit data to remove some irrelevant traces.

Run the command python3 pwic_admin.py split-project --help for further details.

It is not possible to merge two databases into one, which would be the reverse operation.

☝️ Delete a project

Deleting a project cannot be undone. The user accounts are not deleted but their rights are removed from the projects.

The action is done in the console only through the following command: python3 pwic_admin.py delete-project --help.

☝️ Create a user account

The users are created by default as readers. The default password is predetermined by the general configuration variable PWIC_DEFAULT_PASSWORD.

The users must change their password before you can change their authorizations.

To ensure the consistency of the documentation and the audit tables, it is not possible to delete a user account.

With the federated authentication, the user accounts are created automatically. You don't need to create them in advance else two password managements will exist simultaneously. To force the use of OAuth, you must reset the password in the console.

☝️ Change the own password

The form is available in your profile page.

It is recommended to setup Pwic.wiki with HTTPS support so that the passwords cannot be intercepted in clear format. The self-signed certicates cannot be used publicly because they generate bypassable errors in your browser.

☝️ Change the password of another user

The recovery of the lost passwords is an administrative task since Pwic.wiki handles neither emails, nor personal information.

This command creates the user account if it does not exist, but it grants no role on the projects.

Run the command python3 pwic_admin.py reset-password --help for further details.

☝️ Revoke a user

The operation revokes the roles of the user on every project. If this user is the unique administrator of some projects, there are displayed.

The user account is not deleted physically, and replacing it with the default ghost account is not implemented but technically possible.

Run the command python3 pwic_admin.py revoke-user --help for further details.

☝️ Grant the authorizations

The rights are project-dependent. The form is accessible from the special page.

The administrators only can grant new rights to the users if they changed their password once.

A user must have one profile at least (ex: reader) to be able to view the project. To switch from one profile to another for a user, you should first activate the new profile, then deactivate the old profile.

The profile administrator cannot be removed or disabled oneself to ensure that there is always one administrator per project.

The assignment of the rights is monitored. You should also consider the separation of duties: no one should be able to do everything.

The anonymous access is given by the special user account pwic_anonymous. The account cannot be removed. You can disable it or enhance its rights (excluding administrator).

☝️ Create a page

The creation of new pages is restricted to the managers in order to monitor the documentation efficiently. Each page is codified with an external identifier that can be listed alphabetically in each project overview.

If a page is created in reference to another page, its content is copied by default. In that way, you can dedicate a project to store the default templates. It is not possible to refer to a page that doesn't exist or for which you have no access rights.

A page cannot be renamed to ensure the consistency of the documentation and the audit tables.

Each project must contain the home page home. It is accessed by default, it is sorted in first place in the header bar, and it holds the link to the special section of the site. Thus it is not recommended to delete this particular page.

☝️ Modify a page

Text content

A page is a collection of revisions. A new revision is created each time a page is modified. A past revision cannot be updated, but deleted under some conditions.

The tags are the base to classify the pages freely. The keywords are separated by a space. You can search for a tag in the search engine by usign a hash (ex: #tag). A tag counts a lot in the evaluation of the results.

The content of the page follows the Markdown (MD) syntax and you can use HTML markups outside of a code block. The dangerous attributes are automatically removed, but beware to not break the export to OpenDocument.

If enabled by the option mathjax, you can embed mathematical expressions supported by MathJax. As a special constraints, the sign \ must be doubled. For example, the usual form \(\sqrt{x^2}\) should be written as \\(\\sqrt{x^2}\\). Because it is not possible to preview the formulas before saving, you should save your page as draft.

Saving as draft means that you are working on a page. The revision needs no particular attention, except the one of the current editor. You can delete your own drafts. They are also automatically deleted once you publish a final version.

Saving as final means that the document is ready to be reviewed by the validator. It also physically deletes all your own previous revisions marked as draft unless you define the option keep_drafts.

If you want to save a document which is neither a draft, nor a final version, just save it with none of these flags. Such a revision is a milestone and can be deleted by an administrator only.

The attribute Reason of the page is a mandatory text that summarizes the purpose of the modification. It is used in the history to search for old revisions at glance.

The attribute Milestone of the page is an optional free comment that can be used, for example, by the manager to request a delivery date, or by the editor to announce a publishing date. You can also indicate your difficulties, the current progress, etc...

The attribute Header line means that the page is displayed in the header line. It helps to structure your documentation by themes. There is no limitation in the number of header items and only a manager can set the attribute.

The attribute Protected page means that the page can be modified by a manager only.

A manager can change all these attributes without recreating a revision if the option quick_fix is enabled.


You can upload several files for a page. In case it is a picture, you can also include it in the page as a figure, else as a link. All the files are listed on a gallery below the page.

In any case, many rules apply in the uploading process:

For any document stored in the supported formats, you can import its content as a Markdown text by clicking on the button 🔨, unless you defined the option no_document_conversion. The images are excluded from the processing. The embedded convertor produces a more suitable content in regards of what the renown tool Pandoc can achieve.

☝️ Move a page

This feature has two usages:

Because the manager is responsible for the organization of the pages, you must have this role for the source and destination projects. The existing pages are not updated, then broken links will appear.

☝️ Delete a page

You delete a revision one by one, not the entire page at once. Moreover some restrictions apply to ensure the consistency of the documentation.

A manager and an editor can delete their own drafts. An administrator can delete a revision that is neither final, nor validated.

Because of the incremental numbering, the highest identifier of a deleted page can be reallocated. And the gaps in the numbering of the revisions exist by design.

☝️ Read a page

You must have an account to be able to read the documentation, unless the option no_login and the anonymous user are enabled for the concerned projects.

The pages are saved into a cache to improve the overall performances of the server at the cost of the disk space. After certain technical operations or over the time, it might be needed to clear the cache with the command python3 pwic_admin.py clear-cache. To not wait for the on-the-fly caching of the pages, you can regenerate in mass the cache with the command python3 pwic_admin.py regenerate-cache. The cache is not used to export a page or a project.

☝️ Export a page

A page is usually read online but you can export it on your desktop in several file formats.

html - Web page

The export to HTML is a single file that can be opened in your web browser. However, it does not embed the images, the attachments and your custom styles.

By using the feature "Save as" of your web browser, you can save the page and the loaded pictures, but without the attachments.

md - Markdown

This format is the basic content used by Pwic.wiki.

The file can be edited further with a classical raw text editor, but it needs a dedicated application to be rendered nicely.

odt - OpenDocument

This file format is public but it is not a DOCX document. The file can be edited in MS Word, LibreOffice and more.

The export is designed to be very similar to the HTML rendering online, like as if you copied-pasted the text in your editor. However, slight differences of layout are expectable.

The success of the conversion can be altered if you use HTML tags in your pages.

pdf - Desktop PDF

This format is not supported by Pwic.wiki, so it cannot be disabled in the options.

By using the feature "Print" of your web browser, select a virtual printer to produce the final PDF file. When doing so, some useless elements of the page are hidden.

On Windows, you can enable the PDF printer by executing the command %windir%\System32\OptionalFeatures.exe.

☝️ Validate a revision

Several conditions are required to validate a page:

☝️ Export a project

The administrators are able to download a project as a ZIP file containing all the pages and attached documents. The purposes are the creation of a backup or the preparation of a migration for example.

The export is audited and can be disabled by setting the administrative variable no_export_project.

☝️ Verify the links

Pwic.wiki can verify the internal links of the pages to ensure that:

The checks apply within a given project. The links to other projects are neither reported as orphan, nor as broken.

The feature serves as a general monitoring tool for the documentation.

☝️ Graph of the links

The directed graph is a visual representation of the links between the pages. It is possible to detect the pages of high importance and the ones that are insufficiently put into the light.

In case you link to another project, only the targeted pages are displayed. The title of the page is hidden if you don't have access to the project.

The pages in red correspond to broken links.

You can download the graph as a file. After you installed GraphViz, you can regenerate the picture with the command: dot -Tsvg input.gv -o output.svg.

☝️ Search across the pages

The search works with exact literals. If you are looking for the word excellent but the page contains the word exellent (without the c), you won't find any result. Consequently, writing without mistake is a main objective not only for search purposes, but also for the general quality of the documentation.

The search engine doesn't build an index of words. It means that you are able to search within a word. For example, document will match with both document and documents, but documents will match with itself only. Consequently, you should avoid the plural forms to maximize the number of results. This feature is also very important to be able to search for partial technical keywords if the documentation contains lines of code.

You can search for individual words, but also for sentences if you use double quotes. For exemple, "my documentation" will not match with my last documentation. However, my documentation would match with it because there is no quote (my and documentation are processed separately).

You can exclude a term by adding a leading minus sign (-). For example, -interface will exclude all the pages that contain the word interface. You can combine negated terms and they will act as an OR condition. It means that if one of the negated terms is part of the page, then the page is fully excluded. In case you want to search the minus sign explicitly, consider using surrounding quotes ("-interface").

The terms that are not negated act as an AND condition. It means that all the terms must appear so that the page can be selected. That's why you should not use the keyword and explicitly. It is not possible to make OR conditions with these terms, so do separate searches instead.

Some special search terms exist:

At the end, the pages are sorted by the number of occurrences of the search terms. Each term that is not negated contribute to the score as a sum. Because of that, your search terms should be at least 3- or 4-character long.

The search is case-insensitive.

☝️ Search across the documents

The search applies on the name of the page, the file name and the mime of the file.

The syntax of the terms is similar to the one used for the pages. You can use inclusive and exclusive keywords, but not the special ones that contain :.

It is not possible to search within the content of the files.

☝️ View the activity log

All the activities

Pwic.wiki logs many activities to enforce the traceability of the documentation. In case of troubles, it is possible to unwind the events and have a better understanding of the situation.

Online, the administrators of a project can see the events related to the project only, like the creation of a page, a deletion, a validation... At system level, it is possible to display all the events, including the ones not related to a given project.

The listing can be filtered out by date and content with the following syntax: python3 pwic_admin.py show-audit --max 365 | grep grant would return all the modifications of the users' rights over the last year.

All the logins

Run the command python3 pwic_admin.py show-login --days 30 to show the last logins of the users over the last given days (30 by default).

If the users don't delete their cookies and if you use the option keep_sessions, the users won't need to reconnect very often. Therefore an old login date is not necessarily a sign of inactivity.

All the inactive writers

Run the command python3 pwic_admin.py show-inactivity --days 30 to highlight the inactive users who can modify the documentation.

Some projects being completed, it is possible that they have not received any recent modifications by their owners.


General figures about the server and the projects can be summarized by the command python3 pwic_admin.py show-stats.

Archive the log

Because the audit data can grow fast, you can archive the data on a regular basis with the command python3 pwic_admin.py archive-audit --selective 30 --complete 365. In the selective horizon (ie. older than the given number of days), some generic entries are removed but all the core traces of the projects are kept. In the full horizon, all the entries are removed.

In fact, the entries from the table audit are just moved to the table audit_arch and you can dispose of the data at your convenience through SQL commands. To remove the old entries physically, you would execute: DELETE FROM audit.audit_arch.

By design, you cannot remove the entries in the short horizon of 90 days. Also note that archiving the audit data impacts the reliability of the reports above.

☝️ View the activity of a user

The user page contains a public overview online of the recently modified pages (over the last 30 days) and the uploaded documents.

Your own user page is mentioned in the footer.

☝️ Automate Pwic.wiki (API)

The web interface communicates with Pwic.wiki through an application programming interface (API) whose specifications are available online.

You can develop external robots in the limit of your permitted authorizations. Some examples are available in the folder static/api/.

You can add your own paths by extending the source code.

☝️ Report into BI

Through API remotely

The Application Programming Interface (API) is a set of custom HTTP end-points used by the web user interface to perform all the updates in Pwic.wiki via POST requests mostly. All the users have access to a partial set of safe features depending on their online authentication.

The API is usable for the mass automation of the public data in read and write mode. It does not integrate well with BI tools because the data model is not reflected transparently and consistently.

The API cannot be turned off but you can restrict the users by their authorizations for each project.

Through ODBC locally

If you have a direct and local access to the server, you can use an SQLite ODBC driver locally to integrate Pwic.wiki with your favorite BI tool. However, all the data will be exposed without any filter or check. It is a critical point of failure if you leak the values of the private keys stored in the table env.

There is no possible option to prevent the local use of an ODBC driver. The access to the database is restricted by the file system only.

Through OData remotely

OData is a protocol to share data with external systems. Pwic.wiki implements minimalistic features (read-only, no filter, no stream, basic authentication), so that you can query the data remotely for your reporting. The tested tool is PowerBI that is often used in the business environments.

First, you need to activate the OData interface through the global option odata. Its effect is immediate.

Second, the OData feed is available at the following addresses:

The data are filtered from source and the private ones remain hidden. The OData cannot be filtered out by a dollar-argument. An authentication through a challenge Basic applies at the lowest level only. You cannot use the federated authentication (OAuth). For your security within an untrusted network, you should enable HTTPS. The exposed data may differ depending on your authorizations. A basic use of OData is possible with an account having a role of reader on the projects that you wants to report on.

The mass import of the tables in PowerBI via the shortest path is not supported for an unknown technical reason. Instead, you should add each table by its full path, which will require an authentication each time.

☝️ Read the licenses

Pwic.wiki is released under the terms of the GNU Affero General Public License v3+. For more details, refer to the file LICENSE.

Pwic.wiki also relies on several external resources whose licenses are summarized in the following table:

Name Tested version Type License
aiohttp 3.8.3 (>=3.8) Library for Python Apache 2.0 License
aiohttp-cors 0.7.0 Library for Python Apache 2.0 License
aiohttp-session 2.11.0 (>=2.10) Library for Python Apache 2.0 License
cash.js 8.1.0 Library for JavaScript MIT License
EasyMDE 2.12.1 (modified, >=2.12) Library for JavaScript MIT License
FontAwesome 5 Font SIL OFL 1.1
FontAwesome 5 Cascading style sheets (CSS) MIT License
ImageSize 1.4.1 Library for Python MIT License
Jinja2 3.1.2 Library for Python BSD-3-Clause License
Markdown2 2.4.8 (modified, >=2.3.10) Library for Python MIT License
MathJax 3.1.2 Library for JavaScript Apache 2.0 License
Noto Sans 14 Font Open Font License
Parsimonious 0.9.0 Library for Python MIT License
PrettyTable 3.3.0 Library for Python BSD License
pygments 2.14.0 Library for Python BSD-2-Clause License
Python 3.8.6 Programming language Python Software Foundation License
SQLite 3 Database engine Public domain
SVG pan & zoom 3.5.1 Library for JavaScript BSD-2-Clause License
Swagger UI 3.14.1 Library for JavaScript Apache 2.0 License
Viz.js 1.7.1 Library for JavaScript MIT License

🔝 Top of the page 🔝