How to use the MCT Blog ‐ Embedding and Storage of Files - MCT-master/guides GitHub Wiki

< Back to "How to use the MCT Blog"

Blog posts do not only contain text. Most of the time posts integrate images, videos, audio, code, and other documents. Contents that you source elsewhere can be embedded in blog posts (e.g. videos from Youtube or Vimeo, audio from Soundcloud) by giving credit to the original creator.

Original contents that you create for the blog must be stored either in the blog GitHub repository or in the UiO Vortex blog folder for two reasons:

• GDPR compliance - although all data published in the blog is classified as Green, we need to retain full control and ownership of the data in accordance with EU General Data Protection Regulation. The GitHub repository of the MCT Blog and the UiO Vortex blog folder are GDPR compliant, while our own private GitHub and cloud storages are not.

• Sustainability - files in the MCT-master GitHub repository or in the UiO Vortex folder are directly managed by MCT Students and Teachers. When and how things will change depend by us, we have full control over it. For instance, if we decide to move a certain type of data to another sub-folder, we can easily update all existing blog posts automatically. Instead on the long-term, blog data stored in third party repositories can get lost (broken links, embedding disabled, etc.), and there is no way to automate an eventual update (we have to manually check all posts).

Therefore, do not use any of your personal cloud storage services or open hosting services to host data for the MCT Blog. Also multimedia material that you source online, especially images, are not likely to remain there forever. It is recommended that you download them (if allowed) and upload the files (after renaming, more on this later) on the GitHub repository or in the UiO Vortex folder. In the blog post, you should always give credits to the original authors.

All files that you upload in the GitHub repository (under the asset folder) or in the UiO Vortex folder for embedding in a blog post must be named according to the following format YYYY_MM_DD_username_filename.extensionwhere YYYY is the year of the associate blog post, MM is the month of the associate blog post, DD is the day of the associate blog post, username is your UiO username, filename described the contents of the file, and .extension is the extension associated with the file type (e.g. .jpg, .mp4, .mp3, etc.). MM and DD should always be two digits (i.e. do not use 2020_1_1_username_filename.extension for the first of January 2020, but 2020_01_01_username_filename.extension). Do not use capital letters in filenames. Spaces or special characters are not allowed in the file names. It is possible that files are associated or embedded in more than one blog post, in that case the date should be related to the oldest blog post (i.e. where you embedded or linked the files first).

• Path to GitHub blog media folder /assets/images/filename.extension
• Path to UiO Vortex media folder - https://www.uio.no/english/studies/programmes/mct-master/blog/assets/images/filename.extension

Files must be stored in the folders specified in the following guidelines. You should always use the existing folders and never create new folders or sub-folders. Upload files that are only embedded, integrated or linked in blog posts. Uploaded files that are not integrated in any blog post must be removed.

• Images below 300 KB - Images below 300 KB can be stored in the sub-folder of the GitHub repository /assets/image/. Only the following file extensions are allowed: .jpg, .jpeg, .svg, .webp and .png. Jpg compression is recommended as it can provides the smallest file size and it allows to set the quality level (tradeoff between image quality and size). After copying the image to the folder you have to commit and push the changes to the online repository. It is recommended that you do this when the together with your post, when this is ready for publication. Most, if not all, images for your blog post should be within the 300 KB limit. Images for the web are usually optimized to be small in size, allowing fast page loading and requiring less data to be transmitted. We recommend using .jpg for most images, since you can reduce the file size by both resizing the image and by changing the quality parameter. It is very important that you optimize the size of the features image you select for your blog post (ideally not more than 100 KB and 300x300 pixels). Pictures taken with your mobile phone or digital cameras must be significantly resized (original size likely to be of several MB). There is no reason to embed an image of several megapixels when most screens has way less than one megapixel to display an image. To resize and compress images you can use GIMP.

• Images above 300 KB - Sometime you may want to share in your blog post high resolution images. These can be of any size and any extension. You can make large images available for download (recommended), or embed with an iframe allowing users to zoom in and see the details of the image. An exception to this rule are GIF animated images, which are usually large in file size but suitable for embedding. Images exceeding 300 KB must be stored in the UiO Vortex blog folder under /assets/image/. You can upload files using your browser after logging in to UiO Vortex. Go to the right subfolder and click the button Upload file. When uploading the file, tick the box Publish automatically after upload and ensure that the Status of the file is Published when the upload completes. Alternatively click on the uploaded file and then click on the Publish button on the following page.

• Audio, Videos and Documents - Audio, video and document files should be stored in the respective sub-folders of the UiO Vortex blog folder under /assets/. If you think that your file does not belong to any of these categories, use the folder other. When uploading multimedia files always keep in mind that you should use compressed formats (highly recommended as .mp3 for audio and .mp4 for video) if you plan to embed and stream those files though the blog. You can still achieve good audio and video quality adjusting the compression settings. Instead, when necessary, you can use uncompressed formats (large files) for audio and video contents only available for download through the blog (after being zipped). You can upload files using your browser after logging in to UiO Vortex. Go to the right subfolder and click the button Upload file. When uploading the file, tick the box Publish automatically after upload and ensure that the Status of the file is Published when the upload completes. Alternatively click on the uploaded file and then click on the Publish button on the following page.

• Code - When sharing code you have developed through the blog, generally the most appropriate way is to include a link to a public GitHub (or similar) repository that you use to develop, maintain and share the code. However, there are cases in which may not be the best solution. If you have a very small program (e.g. one or very few files), collect all files in a zipped folder, name it as YYYY_MM_DD_username_foldername.zip, and store it in the /assets/code/ folder of the GitHub repository (if the file is bigger than 300KB, upload it in the same location in the UiO Vortex blog folder). Another scenario in which linking an external GitHub may not be the best solution is when you want to execute code in browser (linked or embedded in your blog post), such as Javascript or WebPD. In this case keep all your source files in a sub-folder of /assets/code/ named YYYY_MM_DD_username_foldername. If all files are smaller than 300KB, you can create such folder in the blog GitHub repository, otherwise in the UiO Vortex blog folder. If you need to access or link this code externally (i.e. outside the blog) you can add your folder and file name to the following URL https://raw.githubusercontent.com/MCT-master/mct-master.github.io/master/assets/code/ (for files in the blog GitHub repository) or https://www.uio.no/english/studies/programmes/mct-master/blog/assets/code/ (for files in the UiO Vortex blog folder).

• Direct Download - To create a direct download link use the following Markdown code

  • For files stored in the GitHub repository

    [download link text](https://raw.githubusercontent.com/MCT-master/mct-master.github.io/master/assets/path_to_file)
    

  • For images stored in the UiO Vortex blog folder

    [download link text](https://www.uio.no/english/studies/programmes/mct-master/blog/assets/path_to_file)
    

  where download link text is the text of the hyperlink, and path_to_file is the folder and filename to locate the specific file in the asset folder (case sensitive).

• Embedding images using Markdown - To embed an image in Markdown use the following code

  • For images stored in the GitHub repository

    ![Alternate Text](/assets/image/YYYY_MMDD_username_filename.jpg "Image Title")
    

  • For images stored in the UiO Vortex blog folder

    ![Alternate Text](https://www.uio.no/english/studies/programmes/mct-master/blog/assets/image/YYYY_MMDD_username_filename.jpg "Image Title")
    

    where, Alternate Text is the text that will be displayed in the browser if the image is not found at the specified address (e.g. wrong or broken link), and Image Title is the title (optional) that will be displayed next to the pointer when hovering over the image.

• Embedding images using HTML - Embedding an image using HTML allows you to have better control over the image size, layout, and you can add a caption as well. To embed an image in HTML create use the following code

  • For images stored in the GitHub repository

    <figure style="float: none">
       <img src="/assets/image/YYYY_MMDD_username_filename.jpg" alt="Alternate Text" title="Image Title" width="auto" />
       <figcaption>Caption Text</figcaption>
    </figure>

  • For images stored in the UiO Vortex blog folder

    <figure style="float: none">
       <img src="https://www.uio.no/english/studies/programmes/mct-master/blog/assets/image/YYYY_MMDD_username_filename.jpg" alt="Alternate Text" title="Image Title" width="auto" />
       <figcaption>Caption Text</figcaption>
    </figure>

    where, Alternate Text is the text that will be displayed in the browser if the image is not found at the specified address (e.g. wrong or broken link). Image Title is the title (optional) that will be displayed next to the pointer when hovering over the image, and Caption Text is the caption (optional but recommended) displayed below the image.

    The style="float: none" can be used to specify the horizontal alignment of the figure and of the caption. To do this, simply specify right, left or none (for middle) in the space following float: .

    The width field allows for detailed control of the image size. It is sufficient to specify the width since the content always preserves its aspect ratio. If set to auto the image will be sized to occupy as much space as possible, usually, the entire width of the text column, and the image will be dynamically resized when increasing-decreasing the size of the browser window (this will change the width of the text column). If set to a percentage (e.g. 50%), the image will be sized to occupy exactly the specified percentage of the text column and also in this case it will be dynamically resized when increasing-decreasing the size of the browser window. Finally, if set to a specific number, you specify the exact size of the image in pixels (not dynamically resized). For more information, check out the documentation of the following HTML tags: <img>, <figure>, and <figcaption>.

• Featured image in the frontmatter - Featured images must be small enough in size to be stored in the GitHub repository (ideally not more than 100 KB and 300x300 pixels). Featured images stored in the UiO Vortex blog folder may take significantly longer to load. For the features image in the frontmatter of a blog post use the following code

  image: /assets/image/YYYY_MMDD_username_filename.jpg
  

• Embedding audio using HTML - To embed audio files in HTML use the following code

  <figure style="float: none">
    <audio controls>
      <source src="https://www.uio.no/english/studies/programmes/mct-master/blog/assets/audio/YYYY_MMDD_username_filename.mp3" type="audio/mpeg">
      Alternate Text
    </audio>
    <figcaption>Text Caption</figcaption>
  </figure>

  where, Alternate Text is the text that will be displayed if the browser does not support the HTML audio tag or if the audio file is not found at the specified address (e.g. wrong or broken link), and Caption Text is the caption (optional but recommended) displayed below the audio player. The field type must be aligned with the actual audio file format (e.g. audio/mpeg for file.mp3, audio/ogg for file.ogg, or audio/wav for file.wav). As stated above, we recommend a compressed format for audio embedding. We recommend using the HTML

  tag to have better control over the alignment of the audio player in the post layout and for including the caption. For more options and attributes (such as volume, autoplay, loop, etc.) check out the documentation of the HTML <audio> element. Alternatively you can integrate an audio player that also displays the waveform, as in this post (for details, refer to the post source code).

• Embedding videos using HTML - To embed videos in HTML use the following code

  <figure style="float: none">
    <video width="auto" controls>
      <source src="https://www.uio.no/english/studies/programmes/mct-master/blog/assets/video/2021_03_02_henrikhs_lindsay_pianocow.mp4" type='video/mp4'>
    </video>
    <figcaption>Caption Text</figcaption>
  </figure>

  where, Caption Text is the caption (optional but recommended) displayed below the video. We recommend using the HTML

  tag to have better control over the alignment of the audio player in the post layout and for including the caption. For the width and height fields, refer to the information above related to Embedding images using HTML. If width is set to auto the video will show in its full resolution. If you want to change the size, it is recommended to set width only (e.g. width=800) as the height will be automatically scaled accordingly. Check out the HTML <video> player for more functionalities such as autoplay, loop, thumbnail selection, etc. We recommend compressed format for video embedding. You must ensure that your mp4 media format is supported by most browsers (e.g. MPG H264 AAC). If you are not sure, or if your video does not playback properly (e.g. audio only), consider transcoding it to standard mp4 using this online service.

< Back to "How to use the MCT Blog"