{"id":638,"date":"2022-12-09T18:21:28","date_gmt":"2022-12-09T23:21:28","guid":{"rendered":"http:\/\/www.area46.com\/mjc\/?page_id=638"},"modified":"2022-12-12T12:56:05","modified_gmt":"2022-12-12T17:56:05","slug":"technical-writing","status":"publish","type":"page","link":"http:\/\/www.area46.com\/mjc\/technical-writing\/","title":{"rendered":"TECHNICAL Writing"},"content":{"rendered":"\n
\"\"\/<\/figure>\n\n\n\n

Hosting slate documentation on IPFS was a little different than simply adding static files. For the purpose of this tutorial, we\u2019ll use our slate documentation repository as the code-base we reference.<\/p>\n\n\n\n

The other part to this was some issues we had loading images through CSS, and fonts. For CSS, we found the easiest solution was to reference versions of the images that were hosted on IPFS, linked through our gateway like so:<\/p>\n\n\n\n

One of the main issues we found was that a lot of our files were referencing absolute paths\u00a0\/index.html\u00a0<\/code>.The problem with this was that when viewing the documentation through our\u00a0gateway\u00a0navigating to those links would end up redirecting us to\u00a0https:\/\/gateway.temporal.cloud\/index.html\u00a0which wouldn\u2019t work for any IPFS gateway, but for ours these would trigger ACLs redirecting the user to google. The simplest fix was to alter some paths to relative links. However with the desire to not go through and edit a ton of source files, we were able to script this using simple\u00a0find<\/code> and\u00a0sed<\/code> statements.<\/p>\n\n\n\n

background-image: url('https:\/\/gateway.temporal.cloud\/ipfs\/QmQ8DTkjxE7emKkfbKxYcaaAeAiiXcSNk7kGhKdstgfAwY');<\/pre>\n\n\n\n
Fonts were something we had some initial trouble tackling. Due to the source code which gets imported through css imports, we would end up with code that looked like:<\/p>\n\n\n\n
@font-face{font-family:\"LLAkkuratWeb-Bold\";src:url(\"fonts\/lineto-akkurat-bold-s-da650f3e5d121ff3584d6d7df703def6.eot\");src:url(\"fonts\/lineto-akkurat-bold-s.eot#iefix\"<\/pre>\n\n\n\n
When browsing through our gateway, we would get 404\u2019s for these fonts. When adding the file to IPFS, although the fonts were in a separate folder, IPFS would attempt to load\u00a0fonts\u00a0<\/code>as if they were under our\u00a0style sheets<\/code> folder. The trick to this was changing all\u00a0fonts\/<\/code>to\u00a0...fonts\/\u00a0<\/code>. This is something we were again able to fix using simple\u00a0find\u00a0<\/code>and\u00a0sed\u00a0<\/code>statements.<\/p>\n\n\n\n
When adding the files to IPFS, in order to ensure that all relative links are properly parsed, you\u2019ll want to cd <\/code>into the build <\/code>directory that is created when running bundle exec middleman build --clean <\/code>, and add files recursively, wrapping them in a directory object like so:<\/p>\n\n\n\n
#! \/bin\/bash# used to prep slate build's for hosting on ipfs 
# example 
# .\/slate_ipfs.sh bilbobaggins 192.168.0.1 \/home\/solidity\/go\/src\/github.com\/RTradeLtd\/temporal-api-documentation 
# after uploading, you'll want to untar the file, and add it with `ipfs add -r -w <directory>`REMOTE_USER=\"$1\" 
REMOTE_HOST=\"$2\" 
SLATE_REPO=\"$3\"if [[ \"$REMOTE_HOST\" == \"\" ]]; then  
        echo \"first argument must be remote host to upload files to\"  
        exit 1 
fiif [[ \"$REMOTE_USER\" == \"\" ]]; then  
        echo \"second argument must be remote user of the remote host\"  
        exit 1 
fiif [[ \"$SLATE_REPO\" == \"\" ]]; then     
   echo \"third argument must be the absolute path to the slate repository\" 
   exit 1 
fi# change directory to slate repository 
cd \"$SLATE_REPO\" || exit 
# clean up old files 
rm -rf build build.tar# used to build slate to serve as static files 
bundle exec middleman build --clean# change to build directory, exiting if a failure is detected 
cd build || exit# updates hrefs to work with ipfs and not redirect to an actual web url 
# for example if using non-prepped slate static files with an href like 
# href=\"\/account.html\" on a domain gateway.temporal.cloud, this will redirect # to gateway.temporal.cloud\/account.html 
# by trimming the leading \/ it will be redirected to the ipfs link instead find . -type f -name \"*.html\" -exec sed -i 's\/href=\"\\\/\/href=\"\/g' {} \\; 
# do the same as the above for css files 
find . -type f -name \"*.css\" -exec sed -i 's\/url(\"\\\/\/url(\"\/g' {} \\; 
# do the same for content links 
find . -type f -name \"*.html\" -exec sed -i 's\/content=\"\\\/\/content=\"\/g' {} \\; 
# do the same for css fonts 
find . -type f -name \"*.css\" -exec sed -i 's\/url(\"fonts\/url(\"..\\\/fonts\/g' {} \\;# change back to parent directory 
cd .. || exit# tarball the file 
tar cvf build.tar build# upload tarballed file to remote host 
scp build.tar \"$REMOTE_USER\"@\"$REMOTE_HOST\":~\/<\/pre>\n\n\n\n
What can be improved?<\/p>\n\n\n\n