web_tool: a static bookmark directory you host yourself

What the project is, and the stack behind it

The repository describes itself in two languages as a web site navigation application based on JavaScript, HTML and CSS, used to display commonly used web sites in various industries. The README calls it an online URL navigation tool with a clean interface, supporting submission of links for collection, suitable for individual or team use. The technology stack section is the concrete part: HTML5, CSS3, JavaScript with jQuery, Bootstrap 4 and Font Awesome 5. The primary language of the repository is listed as HTML, and the whole thing is static pages with an assets directory. There is one oddity worth naming. The repository topics list vue, but nothing in the README describes a Vue build, and the stack list is jQuery and Bootstrap 4 with hand written HTML. Read the topics as a label rather than a description of the code.

The features, and the one that is only half implemented

The feature list has six items. The pages are pure static HTML with no backend support required. The design is responsive, so mobile access works. There is a light and dark mode toggle. Categories are clear and quick search is supported. There is a URL submission function for collection management. And deployment is simple, with several supported methods. The first five are all delivered by the files in the tree. The sixth is true in a specific sense that the FAQ makes explicit: the submission function currently stores the data in the browser's localStorage. The FAQ lists the three ways to make it persistent, Vercel Serverless Functions, a configured backend API in Node.js, Python or PHP, or a third party form service such as Formspree or Typeform. So the submission feature works out of the box, but only on the machine that submitted it.

How the content is stored, and how you change it

The content model is unusually simple, and that is the project's main characteristic. The navigation data lives in index.html, and to add or change a link you edit the link area of that file directly. The README shows the shape of a link card, and each card is a div with a class, an anchor that opens in a new tab with rel nofollow, a strong element for the site name and a span for the description. Categories are added in the same file as a titled div followed by a row of cards. The about page is about/index.html, where you edit personal information and contact details, the submission page is commit.html, and the 404 page is 404.html. Styles live in assets/css/, with a custom-style.css for your own overrides and a theme stylesheet alongside it, and the assets directory also carries JavaScript, images and the Font Awesome 5.15.4 icon library. The practical implication is that adding a hundred links means editing one large HTML file by hand.

Running it locally before you deploy it

The quick start is two commands and a browser. You clone the repository and change into it, then serve the directory with any HTTP server and open the address it prints.

git clone https://github.com/geeeeeeeek/web_tool.git
cd web_tool

The README offers three ways to serve it, and the first is the simplest.

python -m http.server 8000

The alternatives are a Node.js server started with npx http-server on the same port, or opening index.html directly in a browser, which the README lists as a third option. Either way you then visit the local address on port 8000. There is a reason to prefer the HTTP server even locally: the project is a single page application style site with client side routing and a 404 page, and serving over file:// will not reproduce the behaviour you get in production.

Deploying to Vercel, which the README recommends

The README presents three deployment routes and marks Vercel as the recommended one, on the grounds that it provides free static hosting and simple deployment. The dashboard route is a sequence of clicks: create a new project, import the Git repository with the Import Git Repository option, authorise GitHub and pick the web_tool repository, then set the Framework Preset to Other, leave the Root Directory at ./, leave the Build Command empty and leave the Output Directory at ./, and press Deploy. The result is a domain of the form your-project.vercel.app, and a custom domain can be added afterwards under Settings and Domains with the matching DNS records. The command line route is the same thing in three commands.

npm install -g vercel

vercel login

vercel --prod

The interactive prompts ask whether to set up and deploy, which scope, whether to link to an existing project, the project name and the directory the code is in, and the README tells you to answer the directory question with ./. GitHub Pages and Cloudflare Pages are the other two static hosts, both driven from their dashboards with the build settings left empty, and Netlify works the same way through Add new site and Import an existing project. The live project is already deployed in three places, on GitHub Pages, on Vercel and on Cloudflare Pages.

The Nginx route, and the two lines that decide how it behaves

For a VPS the README walks through a full Nginx setup, which is the most detailed part of the documentation and the one worth reading carefully. You install Nginx, then put the files in place, either by copying them with scp or by cloning the repository into /var/www on the server.

scp -r ./* user@your-server:/var/www/web_tool/

sudo git clone https://github.com/geeeeeeeek/web_tool.git

Then you write a server block, and two parts of it carry the behaviour. The location block uses try_files $uri $uri/ /index.html, which is what makes the single page app serve its entry point for unknown paths, and the static asset location sets a thirty day expiry with a Cache-Control header of public and immutable for images, stylesheets, scripts and fonts. There is also a 404 page wired to error_page 404 /404.html with that location marked internal, and gzip is switched on with an explicit list of types. You enable the site with a symbolic link, test the configuration with nginx -t, restart the service and enable it at boot, and the README finishes with an optional HTTPS section using certbot and the nginx plugin, plus a renewal dry run.

The gaps: no accounts, no moderation, no analytics of your own

Two limitations are documented and one is not. The documented one is the submission form, which lives in localStorage, so a link submitted on one machine is not visible to anyone else, and there is no queue for a moderator to approve. The README's answer is to add a backend, and the three options it lists are the three ways to do that. The undocumented one is that the whole project is a page of links without a data model, so there is no notion of a user, a saved list or a category managed from an interface; adding a hundred links means editing index.html by hand, which does not scale past a personal reference page. The third point is in the FAQ as well. For site statistics the README suggests integrating Google Analytics, Baidu Tongji or 51.la, and it notes that 51.la is already integrated. That last point is worth a moment of your attention, because a public directory of links with a third party tracker already wired in is a decision someone made for you, and the README also lists search engine optimisation steps, meta tags, a sitemap.xml, submission to search engines and page load time, which are aimed at getting the directory indexed.

Editorial conclusion

Adopt web_tool if you want a self-hosted link directory for a small team or a personal reference page and you are comfortable editing HTML directly, because the entire content model is a handful of files with hand written link cards. Do not adopt it if you need a bookmark service with accounts, per-user lists or a submission queue that a moderator reviews, because the submission form writes to localStorage and there is no server. Before you deploy, read the Nginx server block the README provides, since the try_files fallback and the cache rules decide whether the single page app behaves, and decide what happens to submitted links, because the browser only keeps them locally.

Frequently asked questions

Official sources

1. geeeeeeeek/web_tool on GitHub
2. Issues
3. Project website
4. README