Don’t use a hidden directory

[earthboundkid]

Too late for Vuepress, but maybe not too late for VitePress:

Using a hidden directory for .vitepress is very inconvenient. Users must turn on additional settings in file browsers and text editors to see necessary files to edit them. This makes sense for something like git, where it is intended that you mostly interact with a tool and rarely or never directly edit the hidden directory files yourself, but for VitePress, these considerations don’t fit.

It would make more sense if VitePress was just a thin docs site builder, with the idea that few will customize it, but that’s not the current goal, AFAICT.

Please revisit this issue now and if you disagree, fine, but document it so that it’s clear to users why a hidden directory is a good fit for the project goals.

[Mister-Hope]

Just a dicussion here(I am vuepress team number), I am using vupress since 1.0, and I found nothing bordering me when I am using it on windows. I am using VSCode all the time, and it will show .vuepress folder by default. While on linux, I mostly use the remote ssh in VSCode to connect it from windows, so I do not operate files such as copying some files to public folder. I don't think it's inconvenient, and I don't matter the dot at all. Also, you can access them easily throught typing and giving the xxxxx/.vuepress link to get in the folder when you want to on linux.

So could you explain it with more detail? What's your editor and system? Why are you accessing .vuepress often? And where is the inconvenience from?

[earthboundkid]

Windows is different from Unix, so not really relevant here. In Unix (meaning both Linux and Mac), files beginning with . are hidden by default, and you have to jump through hoops to see them.

[andreasvirkus]

I haven't really heard of developers having issues with dotfiles. I guess the only scenario where I could see this being an issue would be when I'd want to use Finder to move a file from some directory (e.g. Downloads) to my Vue-/Vitepress dir? I think it currently just follows best practises, in a similar manner as Vue plugins hook themselves to the Vue instance with a dollar prefix.

[earthboundkid]

I can’t understand what you’re talking about. How is using a hidden directory like adding a globally visible plugin? There is no analogy in the rationale or pros/cons.

A hidden directory has this pro:

• users won’t accidentally mess with it

Eg for git, this is good because you should interact with git though the command line tool 99% of the time.

Apparently, for Windows and some users of VSCode, the directory is not hidden. Okay, good to know, but also means that you are not relevant because you aren’t affected either way. You aren’t getting the pros or the cons.

The cons are considerable.

• Must document how to unhide the directory for users in their file browser, which is system specific
• If you copy a directory by selecting its contents, you will fail to copy the hidden directory.
• My git ignores files in hidden directories. You have to deal with people opening issues because of being confused by that and either document the workarounds or just “wont fix” them.
• My Sublime Text does not show hidden directories. Ditto.

Etc. the cons are just the flip side of the pro.

If the hidden directory should not be interacted with, the cons are more tolerable, but I think many users will want to customize Vitepress, which makes it a bigger (wholly self-inflicted) support burden and DX pain.

[andreasvirkus]

Your cons are about user setup though. I hope you won't take offence, but you'll face this same problem with a lot of other projects, so I'd rather recommend configuring your file browser and editor to show dotfiles and hidden directories. If you're using Nautilus or something to move around files, pressing Ctrl+H should already be a common practise so you don't skip anything (or doing it via cli).

Secondly, I don't think the dot notation is about protecting the directory so users wouldn't mess with it, since it's there in plain sight for a large portion of users and meant to house your vitepress config, theme, etc. It's more of a visual indicator that everything inside here intends to configure X. That's also why i brought up the dollar-notation for Vue plugins. It represents ownership/belonging rather than hidden or secretive files not to be tampered with (and also of course to reduce the chance of name clashing).

[earthboundkid]

you'll face this same problem with a lot of other projects

Not really? I've been professionally programming for seven years and was a hobbyist for twenty years before that, and I never turned on show hidden files because typically the hidden files are files I don't mess with very often. I think I may have had it turned on ~2004 because Mac OS X was new and I was messing with internals then. Pretty much never otherwise.

So, for example, Nuxt has a .nuxt directory. But that directory is wholly controlled by Nuxt and is just a cache of some sort. You add it to your gitignore and never touch it. I never see it and I never want to see it. Github has a .github directory for CI configuration. You set it up once at the start of a project and then never touch it again unless it breaks. That's my typical interaction with hidden directories.

I'd rather recommend configuring your file browser and editor to show dotfiles and hidden directories.

Then why use a dot directory at all? If you just want it to alphabetize first, use underscore. Underscore is commonly used, eg by Jekyll, to indicate directories related to a project internals but that you should manually configure. Your argument is that everyone should use hidden directories but not use them as hidden. That makes no sense. If the whole idea is to unhide it, then why hide it in the first place?

It's more of a visual indicator that everything inside here intends to configure X.

That's what underscore does. Dot is for hidden files.

[nkconnor]

(new user of VuePress). It is bewildering to me why this is a hidden directory. Is there any docs on how to rename for a project?

What's your editor and system?

vim, linux

Why are you accessing .vuepress often?

editing CSS, components, configuration

And where is the inconvenience from?

it's a hidden directory

EDIT: looks like I'm not even in the right project. Judging from the other immediately closed issues in vuepress, having your main development files in a hidden directory is well loved. Still wondering, why?

[earthboundkid]

Judging from the other immediately closed issues in vuepress, having your main development files in a hidden directory is well loved.

My guess is that for many users, it's not a hidden directory (as Mr Hope and Andreas indicate for themselves above), so it's not inconvenient to them. I think it would be best to use underscore, so the message of "internal by convention" is still sent but without all the inconvenience for users who actually have dot directories hidden.

[yyx990803]

Just curious - you've never used .eslintrc.js, .gitignore, .npmignore, .prettierrc, .circleci, .github, .vscode or the likes?... it seems to be a very common convention when it relates to development tooling.

[nkconnor]

@yyx990803 yes but usually edited rarely as opposed to being the main development files (for example my .gitignore file changes less than once a month). Perhaps I'm using vuepress incorrectly. Right now my workflow is editing these files to make UI changes in real-time:

.vuepress/
  components  config.js  enhanceApp.js  public  styles

Personally, I've never ran into a project that chose a hidden directory for their main project files. I would be just as curious if https://github.com/vuejs/vue had the src directory named .src.

[earthboundkid]

1) Those are tooling, so I edit them fairly infrequently. Typically, they only need to be tweaked when a project starts or a major tool is upgraded. I personally prefer to use non-hidden names when possible (e.g. postcss.config.js).

2) Hidden files are less hidden than hidden directories for me. My Sublime Text set up shows hidden files but does not show hidden directories. I don't know if this is an unusual configuration, but that's how my computer is setup. So e.g., Github's hidden .github directory is kind of a pain in the ass. Fortunately, you can set that up in the Github website GUI, and it basically never needs to be tweaked once you do.

FWIW, if you search around, you can find a thread where Rob Pike explains that dot files being hidden was basically a bug in early Unix (it was just supposed to hide . and ..), and he wishes it had never been invented. :-) The thread was originally on G+ so you have to find a mirror somewhere.

[yyx990803]

@nkconnor it's not that you are using it wrong, but you are definitely not the typical user. Most VuePress users use it for generating docs with minimal configuration. The main files of the project is the markdown files, not the config inside .vuepress.

The reason it starts with . is also because Vue/VitePress uses the file system for determining site structure. Seeing it starts with a dot you can be sure it's not going to be considered as part of your content.

[earthboundkid]

It would make more sense if VitePress was just a thin docs site builder, with the idea that few will customize it, but that’s not the current goal, AFAICT.

So it sounds like the project goal is to continue to be thin “docs site” builder instead of a general purpose static site generator. If that’s correct, I can just close this because that’s the resolution to this issue.

[akauppi]

I got curious to see what's my project's dot-vs-not ratio. Turns out it's 10:7 (1.4).

These are the tool based files and folders, in the project root.

First the dots:

.cache/
.editorconfig   
.eslintrc.cjs    
.firebase/    
.firebaserc  
.git/    
.github/    
.gitignore     
.idea/    
.npmrc    

These are mostly "invisible" cache and setting entries (4). Rarely changing configurations (4). Normal configurations (2). I consider .eslintrc.cjs and .github/ (CI/CD) as the latter.

On the "not" side:

firebase.json       C
firestore.indexes.json   B
firestore.rules  C
node_modules/   A
package.json  C
rollup.config.prod.js   C
vite.config.cjs   C

Here, I'd say cache and settings entries 1, rarely changing 1, normal 5.

So based on this completely inadequate sample size ;) it seems more config files/folders use dot, but of the "not"s more are configuration files the user is expected to tune, frequently.

Note that Vite config is in the "not" camp.

I don't want to turn anyone's boat. My personal preference is for "not", and I'm merely trying to provide data to help steer the decision. 2¢

[kiaking]

I think we can close this now, since it's not really super important and also it make sense to follow VuePress config style (at least for now).

[davestewart]

If anyone needs to toggle hidden files / folder on OSX, Shift+Cmd + . will do that in the Finder.

[kissu]

Also, I guess that most people do not navigate via mouse but with cmd + p and directly the name of the file, hence no issues there. Another thing that can be done is to pin something in your VScode, that way you still have access to it quickly and it does not take a lot of space.