I have a few different projects and a ton of tutorials I want to host on the same http server... is this possible? I watched the Host and automate your DocC documentation session, but it seemed to only work with those rules for one docarchive.
I know someone filed feedback for prefixes (https://developer.apple.com/forums/thread/682276)... is this possible already?
Thanks.
This should be possible already as you suspect. There will need to be additional server routing configuration to map the right requests for data URLs to the right doccarchive where the data actually lives.
For example, the same server could rewrite URLs for multiple frameworks/doccarchives so that the following applies:
/data/documentation/A should map to A.doccarchive/data/documentation/A.json/data/documentation/B should map to B.doccarchive/data/documentation/B.jsonThe example Apache configuration from the "Host and automate your DocC documentation" is hardcoded to the one SlothCreator.doccarchive example, but this configuration could be generalized to support more than one doccarchive.
If you can provide the specific server technology you're using (apache/nginx/etc), someone can probably help provide more explicit details on how to perform that kind of routing/rewriting for your exact use case.
But you can't just do:
RewriteRule ^(css|js|data|images|downloads|favicon.ico|favicon.svg|img|theme-settings.json|videos)/.$ A.doccarchive/$0 [L] RewriteRule ^(css|js|data|images|downloads|favicon.ico|favicon.svg|img|theme-settings.json|videos)/.$ B.doccarchive/$0 [L]
I can only use just one of them, so I can only host either /documentation/A or /documentation/B
In my case I use nginx with:
location documentation/a { alias /usr/share/nginx/html/A.doccarchive/; index index.html index.htm; }
location / { root /usr/share/nginx/html/A.doccarchive/; }
I can't just do this obviously:
location documentation/a { alias /usr/share/nginx/html/A.doccarchive/; index index.html index.htm; }
location / { root /usr/share/nginx/html/A.doccarchive/; }
location documentation/b { alias /usr/share/nginx/html/B.doccarchive/; index index.html index.htm; }
location / { root /usr/share/nginx/html/B.doccarchive/; }
It is possible that I'm misunderstanding the use case described in the above comment, but here is one way of doing the same thing described in the answer with Nginx instead of apache if it is useful:
server {
...
location /data/documentation/A {
root /path/to/A.doccarchive;
}
location /data/documentation/B {
root /path/to/B.doccarchive;
}
location / {
root /path/to/A.doccarchive;
try_files $uri $uri/ /index.html;
}
}
(Apologies if the formatting doesn't come through as expected)
Thank you for your feedback. But sadly it still doesn’t work only for /documentation/a but not /documentation/b, on the webpage it says: An unknown error occurred. Probably because “locations / { root /path/to/A.doccarchive; try_files $uri $uri/ /index.html; }” doesn’t work for B.doccarchive. And you can’t define a second “locations / { root /path/to/B.doccarchive; try_files $uri $uri/ /index.html; }“ when you already have “location / { root /path/to/A.doccarchive; try_files $uri $uri/ /index.html; }” defined.
This should be possible already as you suspect. There will need to be additional server routing configuration to map the right requests for data URLs to the right doccarchive where the data actually lives.
For example, the same server could rewrite URLs for multiple frameworks/doccarchives so that the following applies:
/data/documentation/A should map to A.doccarchive/data/documentation/A.json/data/documentation/B should map to B.doccarchive/data/documentation/B.jsonThe example Apache configuration from the "Host and automate your DocC documentation" is hardcoded to the one SlothCreator.doccarchive example, but this configuration could be generalized to support more than one doccarchive.
If you can provide the specific server technology you're using (apache/nginx/etc), someone can probably help provide more explicit details on how to perform that kind of routing/rewriting for your exact use case.
But you can't just do:
RewriteRule ^(css|js|data|images|downloads|favicon.ico|favicon.svg|img|theme-settings.json|videos)/.$ A.doccarchive/$0 [L] RewriteRule ^(css|js|data|images|downloads|favicon.ico|favicon.svg|img|theme-settings.json|videos)/.$ B.doccarchive/$0 [L]
I can only use just one of them, so I can only host either /documentation/A or /documentation/B
In my case I use nginx with:
location documentation/a { alias /usr/share/nginx/html/A.doccarchive/; index index.html index.htm; }
location / { root /usr/share/nginx/html/A.doccarchive/; }
I can't just do this obviously:
location documentation/a { alias /usr/share/nginx/html/A.doccarchive/; index index.html index.htm; }
location / { root /usr/share/nginx/html/A.doccarchive/; }
location documentation/b { alias /usr/share/nginx/html/B.doccarchive/; index index.html index.htm; }
location / { root /usr/share/nginx/html/B.doccarchive/; }
It is possible that I'm misunderstanding the use case described in the above comment, but here is one way of doing the same thing described in the answer with Nginx instead of apache if it is useful:
server {
...
location /data/documentation/A {
root /path/to/A.doccarchive;
}
location /data/documentation/B {
root /path/to/B.doccarchive;
}
location / {
root /path/to/A.doccarchive;
try_files $uri $uri/ /index.html;
}
}
(Apologies if the formatting doesn't come through as expected)
Thank you for your feedback. But sadly it still doesn’t work only for /documentation/a but not /documentation/b, on the webpage it says: An unknown error occurred. Probably because “locations / { root /path/to/A.doccarchive; try_files $uri $uri/ /index.html; }” doesn’t work for B.doccarchive. And you can’t define a second “locations / { root /path/to/B.doccarchive; try_files $uri $uri/ /index.html; }“ when you already have “location / { root /path/to/A.doccarchive; try_files $uri $uri/ /index.html; }” defined.
Thanks for the quick response! So I'm planning on using Apache and having a setup that looks like, for example, this:
~/public_html/docs/question_bot
~/public_html/docs/slothcreator
But before I even get to serving up the two separate doc archives, when I navigate to question_bot, I have an issue loading the css and js folders at the root, because in my public_html folder I already have css and js files that drive other parts of this site. So this rewrite rule in the .htaccess file is a bit of an issue:
# Route files within the documentation archive.
RewriteRule ^(css|js|data|images|downloads|favicon\.ico|favicon\.svg|img|theme-settings\.json|videos)\/.*$ QuestionBot.doccarchive/$0 [L]
(This rewrite rule is in a .htaccess file in the ~/public_html/docs/question_bot directory.)
Is there an easy way to amend this to not stomp all over my existing content? I can go digging into rewrite rules and regexp, but if there's an obvious way to support the setup above (and avoid requests for my docs going to /css and /js) I'm missing I'd love to hear it.
Thanks!
It may depend on the exact conflicts that you're running into and how flexible you are with the structuring of your own existing content.
It sounds like the problem you're running into is that you have your own existing assets set up in possibly the same structure as the assets in the documentation archive—for example, you also have a top level css/ folder like the archive does.
Solution 1: If that's the case, the easiest way to avoid this problem would be to add a new directory for your own existing assets so there is no conflict anymore—if your current setup is flexible, you could simply add a new public_html/assets/ directory where you could move your existing CSS directory, etc—then, the website will request them from a URL with a relative path beginning with /assets, which would not conflict with the documentation archive asset requests anymore. That may be difficult depending on how easy it is to restructure your existing files of course.
Solution 2: Another possible solution is that you could have more explicit rewrite rules so that Apache rewrites URLs for things like /css/your-existing-file.css to the right folder—adding a more detailed regular expression is one way to avoid conflicts without restructuring your assets but might not be a very scalable solution and won't work if you have exactly the same filenames in your CSS folder (highly unlikely this is the case though).
In any case, the .htaccess file should likely be moved up so that it is in a directory that has access to both .doccarchive files (most likely public_html/docs). Since it is used to configure rules for subdirectories, you'll want both archives to be accessible from below a single parent directory.
Thanks a million for the help. I got it deployed on a new subdomain to avoid conflicts, but these answers helped me understand a little better how it was structured, and I spent a bit of time digging around the data/ folder so I think I've got a better handle on organizing my tutorials and redirects. I really appreciate the help!
I've been playing with this and managed to get it to work on a single domain. I noticed most of the files had a hash at the end of them, so I merged them all down into a single .docarchive file. Of course, this may break in the future, but for now it works
# Delete existing .doccarchive
rm -rf templates/AllProjects.doccarchive
# Create a working folder
mkdir templates/working_dir
# Copy most files, excluding the index and metadata.json files to the working directory
rsync -a --exclude 'index.html' --exclude 'metadata.json' templates/ProjectA.doccarchive/* templates/working_dir
rsync -a --exclude 'index.html' --exclude 'metadata.json' templates/ProjectB.doccarchive/* templates/working_dir
# Copy across the index.html file from each Archive, but give it a new name when copying
rsync templates/ProjectA.doccarchive/index.html templates/test/projectA.html
rsync templates/ProjectB.doccarchive/index.html templates/test/projectB.html
# Create a new .doccarchive folder
mv templates/working_dir templates/AllProjects.doccarchive
You can then host this on your server and point to /documentation/ProjectA or /documentation/ProjectB.
There is one current drawback I can see, the table of contents isn't unique.