xy2z/pinedocs

A fast and lightweight site for viewing files

PineDocs

A fast and lightweight site for viewing files.

Great for documentation, wiki, examples, notes, documents, galleries, storage, etc.

---

Docker Hub | Screenshots | Setup | Configuration | Sponsor

---

See more screenshots at https://imgur.com/a/15Gq67X

Sponsor

💚 Please consider sponsoring or donating to keep this project active - https://github.com/sponsors/xy2z

Features

• No database.
• No building.
• Fast - using ajax and cache.
• Supports Markdown, plaintext, HTML, code, images, SVG, GIFs, MathJax, PDFs, audio and small videos. Basically anything you can render in a browser.
• Responsive layouts and different color schemes (see screenshots here)
• Syntax highlighting for over 169 languages with over 77 themes.
• Configuration (see below).
• Quick filtering in files.
• Use your existing files or existing git repos as content.
• Files are cached client-side after first view, so it loads instantly.
• Hidden folders - only accessible via direct links.
• Remembers scroll position per page.

Read-Only Site

PineDocs is read-only, meaning you can only view files and not edit them via PineDocs. This is not a wiki replacement with user login, revisions etc. This is basically a simple site that renders everything in your content dir. So you need to edit the files on your server/PC in order to change the content.

Setup

Docker

Docker is the easiest way to setup PineDocs.

Docker-compose.yml

version: '3'

services:
  web:
    image: xy2z/pinedocs:1.2.5
    ports:
      - 3000:80
    volumes:
      - ./data:/data/pinedocs

After running docker-compose up -d you can change the config in ./data/config/config.yaml, and add your files (or git clone your repository) in the ./data/files dir.

Changes will take affect when you reload the page - no need to restart the container.

Docker

Altough docker-compose is recommended, you can also use pure Docker:

docker run -itd -v "$PWD"/data:/data/pinedocs -p 3000:80 xy2z/pinedocs

See more at https://hub.docker.com/r/xy2z/pinedocs/

Manual Setup

Requirements

• PHP 8.0 (mininum required php version is PHP 7.2.5)
• Composer for dependencies.
• A web server (apache2, nginx, etc.)

Setup guide

1. Download the latest release or run git clone
2. Run composer install in the root to get dependencies.
3. Setup the web server to the PineDocs/public dir (use php -S localhost:89 -t public for testing)
4. (Optional) Rename the file config/config-example.yaml to config/config.yaml for changing settings (see below)
5. (Optional) Rename the file config/mathjax-example.js to config/mathjax.js for changing settings of Mathjax (see below)
6. (Optional) Change the file config/custom.js when using Docker to customize Javascript
7. (Optional) Change the file config/custom.css when using Docker to customize CSS

Configuration

Feel free to edit the config/config.yaml file to fit your needs.

You can configure Mathjax by editing the config/mathjax.js file.

Settings

• title (string) The title of the site, used in logo, tabs and bookmarks.

• content_dir (string) Path to the dir you want to use. Default is the PineDocs/content/ dir.

• index (string) Relative path to the index file. Default is array of index.md, index.html, index.txt, index.

• layout (string) Available layouts: default, wiki.

• color_scheme (string) Available color schemes: pinedocs, simplistic, simplistic-dark, twilight.

• highlight_theme (string) The theme to use for code. See a list at https://highlightjs.org/static/demo/

• code_transparent_bg (bool) If true, all will use the highlight theme. If false, the background will be transparent.

• open_dirs (int|string) The number of levels of dirs that should be opnened on page load. Use all to open all dirs.

• render_footer (bool) Render the menu footer?

• exclude_files (array) List of files or dirs to exclude. Supports regex if the format is /regex/i.

• show_file_extension (bool) Show file extensions. Default is true.

• menu_link_format (string) Values: default, ucfirst, ucwords, uppercase, lowercase.

• render_max_file_size (float) Max file size (in MB) to render. If file is larger, a download link will be shown. Default is 50.

• font_family (string) The font used for menu and content. Default is Tahoma.

• font_size (string) The font size in menu and content. Default is 15px.

• no_extension_markdown (bool) Render files with no extension as markdown, eg README. Default true.

• break_code_blocks (bool) Break code blocks in multiple lines instead of horizontally scrolling. Default false.

• hide_folders_in_navigation (array) A list of folders to hide from frontend navigation. Case-insensitive. Default is none.

• enable_mathjax (bool) Enable MathJax. Must be enabled for mathjax.js to work. Default is false.

License

GNU GPLv3. See LICENSE.txt

pinedocs's Issues

New config: Format top folders as "categories"

A new boolean config setting for rendering top folders as categories or folders.

Folders is how it is now - a tree view
A "categories" rendering example could be: https://docs.gitbook.com/
So if a folder is named "Getting started" all files are rendered below, without an option to show/hide files.

config name could be something like nav_folder_tree (default true)

Add phpunit testing

Improve themes and color schemes

• The wiki theme doesn't seem to go full width
• Update readme.md
• Add background-color for search bar in each colorscheme
• Rename color_theme to color_scheme
• Update config-example.yaml on difference between a theme and a color scheme
• Show an error message on unknown theme/color scheme (and set it to default?)

Show error message when file is not found on direct links

If a user goes to a /#doesnotexist link and the file doesn't exists, it currently shows a blank page.
It should show a 404 error message.

Latex support

Hello,

I really like the project, but I think that one important thing is missing, the support of LaTeX for mathematical formulas in markdown files (or even KaTeX?).

Like $expression$ renders the formula inline (like a `code`) and $$expression$$ renders it in a new line centered (like a ```code``` but centered)

Is this a feature that is planned for the future?

New PineDocs logo

Make 2 new logos, 1 for light background and 1 for dark background.
The shadow doesn't look cool :)

Also find a new font...

Favicon

Support for FLAC files

Support .flac audio files.

Add hidden folders

When creating a folder with a name like .test it should not be listed on the left side but should be accessible through a direct link.

Show download link if files are too big

Show a message explaining that the file is too big and that can be downloaded.

The question is how to know if the files is too big. I think if the file exceeds php_memory_limit the file is too big, but i'm not 100%.

responsive height

If some folder has a lot of subfolders, the height is truncated.

Sample without expand option:

If I expand a node with several subfolders:

As you can see the last option are not showed

Remove the develop branch

Since docker hub autobuild is disabled on master branch after the price changes, we dont need the develop branch, its easier to just focus on the master branch, and then manually build images on each release in docker hub from the master branch.

• Update Readme & Contributing file
• Remove branch

Rename 'theme' to 'layout'

There may be some confusion about the difference between a theme and a color-scheme, so 'theme' should be renamed to 'layout'.

No programming skills required for this issue.

• Make sure to rename all instances of 'theme' in the code to 'layout'.
• Remember README.md and config/config-example.yaml files.
• Also replace directories from 'themes' to 'layouts'.
• highlight_theme should not be changed.

If you have any problems let me know.

Render SVG images

SVG images are not rendered...
See src/PineDocsFile.php and public/js/PineDocs.js "render_file" method.

Question - Relative paths for images

Hey there,

how would one go about adding images to a document that are available in the filesystem?
I tried everything, but I just can't get it to work.

What I tried so far:
/index.md
/giphy.gif

Inside index.md:

![welcome2](giphy.gif)
![welcome2](/giphy.gif)
![welcome2](./giphy.gif)

But whatever I do, I always receive a 404.

When I checked the developer tools in Firefox,
I saw how the markdown files are retrieved:

/?&action=get_file_data&relative_path=index.md

When I replaced index.md with giphy.gif, It did load the image file.

Prevent line breaks in code blocks

It would be great to have the option to prevent line breaks in code blocks. The user should be able to horizontally scroll in individual code blocks.

New layout: Gitbook inspired layout

light top bar: https://docs.gitbook.com/
dark top bar: https://www.ngxs.io/ (prefered as default)

Related: #98 to render folders as "categories".

Change Logo on Docker

Right now it's not possible to change the logo when using Docker, since the logo is in the public dir.
Make a new dir for logo in /data/pinedocs that is a symlink in the public dir, so it can be reached.

Filter-search should include folders

Right now it's only filenames

Docker-compose.yml example in the README

Link to header in the same document not working

In one of my Markdown files there is a Heading with the title: # Example Header
This link should lead to it: [example](#example-header)
But instead it throws the following error: Error: could not load file: test-header File not found.

Show pretty error message if content-dir does not exist

Or cannot be read. Right now it's just php error messages.

Clicking an file sends 2 of the same AJAX posts

Search (filter in filenames)

A search field above the menu for filtering filenames and directories (not content).
The filtering should be instant, via JS, so no search button is needed.

Pressing the 'F' should focus on the field.
Pressing esc while in the field, the value should be cleared and the complete menu should be shown.

Add phpstan

with --dev
with level 4 or 5.

Show error message if content doesn't exist

or isn't readable

Javascript: Bind '*' key to recursively open all directories

When clicking the '*' on the keyboard, all directories including subdirectories should open up.

See public/js/PineDocs.js set_events method.

Possible to hide_folders_in_navigation for root folder

Would it be possible to also blacklist root folder? I tried with 1.1.5

hide_folders_in_navigation
 - *

but then app stopped to work completely. The purpose is to have shorter URLs, whereas with subfolder there's extra depth in URLs and I would very much prefer no public content only direct links for everything including root folder. Or is it possible already?

Dockerfile

Make a Dockerfile

Support for external links (.url extension)

For docs, bookmarks, etc. it can be very useful to have external links directly in the sidebar.

So for .url extensions open the URL parameter in a new window directly.

Another solution could be to just make a new config option called "external_links" and render them over/under the current navigation.

New Setting: Uppercase first letter of menu link

New setting to render the menu links and dirs as uppercase/lowercase/ucfirst/ucwords/

Update "marked" for markdown

To latest version

https://github.com/markedjs/marked/releases

Download files that can't be rendered

Files that can't be rendered in a browser (like a .docx, .dll, .exe etc) should be downloaded automatically to the user on click.

Use PHP's readfile() and setting the header to attachment.

Remember to validate the user doesn't have access to anything outside content dir!

This could also be a fix for large files that can't be sent through ajax.

Remember scroll position when browsing between files

When browsing to a new file, the browsing position on the file should be saved in JS (not cookies) so when the user clicks back to the file, it is at the same scroll position.

Should also work when using the browsers back/forward navigation.

Add a "copy" function for each code block

For each code block (<pre><code>) there should be added a "copy" icon in the top right position.
When you click the icon, it should copy the content of the code block.
Should also include a tooltip that says "Copy" on hover and then "Copied!" on click.

It should work exactly like this page: https://www.ngxs.io/recipes/authentication

Please use SVG for the icon

MermaidJS

Are there any plans to add mermaidJS in the future?

If @xy2z is ok with that I can try to add it to PineDocs

Upgrade to PHP 8.1

PR is ready at #166 but it needs testing

use exclude_file to exclude dirs too

Hi! Thanks for your project 👍
I had set up PineDocs, and faced with one problem:
I was not able to exclude particular dir, .stversions in my case (syncthing service dir).
My proposal is to exclude file before PineDocs goes to scan it if $item is a dir
PR: #112

This is only proposal, so feel free to close issue & PR at any time

Show error message if config.yaml doesn't exist

External links should open in new tab

When clicking any link, Javascript should check if the link is external, and if it is it should open in a new tab.

See public/js/PineDocs.js

Improve first-time setup experience

• if config.yaml doesn't exist, php should create it by copying config-example.yaml to config.yaml

• public/index.md should contain a welcome and more detailed setup guide. And tips (ex. F key is for searching)

• content/* should be gitignored

• Update readme setup guide, skip the config steps.

• Merge settings, since no setting no longer is required. Config-example.yaml, readme and code.

CSS for blockquotes

This need styling

Use Composer yaml package instead of PECL yaml

To make it easier (for non Docker users) to setup, use this package https://packagist.org/packages/symfony/yaml to read the Yaml file.

And remove YAML Pecl as requirement and from wiki.

Relative path for image support

Find images correctly with a relative path to render the image correctly in markdown.

Example:

                ┌────────────────────────────┐
                │                            │
                │   # Here an image          │
                │   ![Image](Folder1/pic.png)│
                │                            │
Root            └────────┬───────────────────┘
  │                      │
  │                      │
  │                      │
  ├───file.md ◄──────────┘
  │
  │
  └───Folder1
      │
      │
      └─────pic.png

Apache config example file

Add a example config for apache2 in the /examples dir.

PDF Support

Is it possible to add support for PDF display?

Bug: Favicon doesn't work

It works on dev, but not when i deploy on docker.
For some reason the whole /icons dir is forbidden and /icons/favicon.ico returns not found...

Custom marked configuration

Hello, it would be handy if I could change the marked options in the config.yaml file or like the one in mathjax.js.

Or only some parameters like breaks, gfm, mangle, pedantic, smartLists and smartypants which are booleans that change how the text is rendered ?

Add security headers

CSS: Fix wiki theme content width

The 'wiki' theme isn't done
The content width should be 100% - and responsive