diff --git a/website/src/docs/faq/downloads.md b/website/src/docs/faq/downloads.md index 345c1506..2501ecfd 100644 --- a/website/src/docs/faq/downloads.md +++ b/website/src/docs/faq/downloads.md @@ -42,3 +42,33 @@ No, you must choose a single location. Internal storage performs better than ext However, in some cases, this might not function as intended. A quick solution is to create the `.nomedia` file yourself, name it as such, and place it in your downloads folder. If the issue pertains to local source, put the `.nomedia` file in the respective local folder. + +## How are downloads organized on the filesystem? +They are stored as `downloads/Source Name/Manga Name/Chapter Name (abcdef).cbz`. +The `abcdef` string is the first 6 hexadecimal digits of the MD5 hash of the URL of the chapter, so that if two chapters have the same name, they won't try to write to the same filename. +In the case of a scanlator, it is `Scanlator Name_Chapter Name` instead of just `Chapter Name`. + +Because of the prevalence of operating systems like Windows which have arbitrary limitations on special characters in filenames, by default Mihon will avoid using certain characters in filenames, specifically: `"*:<>?\|`. +Of course, `/` is also banned. +All of these characters are replaced by underscores if they appear in source, manga, chapter, or scanlator names. + +Some users have reported using exceptionally buggy operating systems which also have problems with other Unicode characters, such as (but not necessarily limited to) emojis. +If you must use Mihon with such an operating system, you can enable the option in the advanced settings for "Disallow non-English filenames", which will prevent any non-English (non-ASCII) characters from being used in filenames. +Such characters will be replaced with their hexadecimal representations instead. +The special characters mentioned above are still replaced with underscores, if present, rather than hexadecimal. + +None of the above considerations affect the way series and chapters are displayed in Mihon, which is based on their metadata rather than filenames. +Because the local source reads comic metadata files, if present, its functioning is also not affected by filename changes if you convert an external source download directory into a local source directory. + +If you need to change the "Disallow non-English filenames" option, you may need to do some manual work to ensure that Mihon can still find your existing downloads. +Chapter filenames do not need to be changed, as Mihon is able to check multiple options for a chapter filename, and will find the already-downloaded chapters. +Manga and source directory names, however, need to be updated manually if they contain non-ASCII characters. +Here is an example: + +```text +./例 ソース (ALL)/最高のマンガ!/Scanlator Name_始まり_182cce.cbz +./e4be8b20e382bde383bce382b9 (ALL)/e69c80e9ab98e381aee3839ee383b3e382acefbc81/Scanlator Name_e5a78be381bee3828a_182cce.cbz +``` + +The inability for a device to handle Unicode characters in filenames is a bug. +Please consider contacting your device or operating system vendor to report this, or consider using a standards-compliant device in future, if possible. diff --git a/website/src/docs/guides/local-source/index.md b/website/src/docs/guides/local-source/index.md index 85eb3940..4a519c33 100644 --- a/website/src/docs/guides/local-source/index.md +++ b/website/src/docs/guides/local-source/index.md @@ -82,6 +82,9 @@ You can refer to the following example: Mihon will see three chapters in a single series. The path to the folder with images must contain both the series title and the chapter name (as seen above). +Note that this is the same folder structure used by downloads of non-local sources. +However, the filename format is not required to be the same; for example, Mihon adds a disambiguating hash based on the chapter URL when downloading chapters, but you do not need to do this. + ### Archive files Archive files such as `ZIP`/`CBZ` are supported but the folder structure inside is not.