I would like to use the {% include {file path} %} in my MD file.
But I have to place actual file in outside the _includes folder.
Example :
{% include …/testfolder1/testfolder2/testfile.cs %}
If I tried the above line it shows the below failure.
Invalid syntax for include tag. File contains invalid characters or sequences: …/testfolder1/testfolder2/testfile.cs
Let me know how to achieve this ?
Could you please explain the specific use case for why you cannot use the _includes folder? It is possible we can help you identify a better solution for what you are currently doing.
You cannot use a ../folder/file pattern with the include option, which you are asking for. However, you do have a few options:
Move the file(s) you want to include to the _includes folder. Note that you can use a sub-folder structure so that you can type something like this: {% include subfolder/testfile.html %} and that will translate to _includes/subfolder/testfile.html
Use include_relative to include a file in the same folder structure of the calling file or a subfolder of the location of the calling file. For example, let’s say you have a file in the folder products/all.html. Within that file, you can include another file like this: {% include_relative categories/list-categories.html %}, and that will translate to /products/categories/filecategories.html
I have not tested this, but the Jekyll documentation does suggest you can modify your _config.yml to override the includes_dir to another location. If you do not like the default _includes, I believe you can put a line in your _config.yml file that looks like this: includes_dir: _customincludes (you will have to manually create the _customincludes folder and place any files in there. Note: This method does not add a new includes folder, it is replacing the default, so there may only be one formal includes folder.
There is detailed documentation on how to use includes here:
Here is the documentation that suggests you can modify the location of the includes_dir:
Hi @ BillRaymond
Thanks for the update. Please find the requested details below.
Query : Could you please explain the specific use case for why you cannot use the _includes folder? It is possible we can help you identify a better solution for what you are currently doing.
Ans : We have many git repositories. If the files need to be present in the _includes , we have to copy the files from other location to _includes. To avoid this copy work , we have tried to update the exact location.
New query from my end
Now, I think the 2nd solution (include_relative) will be help us. But I have below query on this. Could you please clarify this ?
I have html and .cs file in the same folder. I have to load the code from the cs file to the html.
So that I have added the below examples lines in the html file. It shows the code snippet as expected in both case.
Case 1
csharp** **{% include_relative test.cs %}** **
Case 2
{% highlight c# %}
{% include_relative test.cs %}
{% endhighlight %}
Now I have to know whether include_relative can accept all file extension (programing language) ?
Ex : cs , xaml , cshtml , html, Etc…
Thanks in advance.
HI @BillRaymond
Thanks for the update.
Please find the answer for your query below.
Q : Could you please explain the specific use case for why you cannot use the _includes folder?
A : Our code snippet file will be present in various location (for example various repository). That’s why we have tried …/folder/file pattern.
Now , we would like to use the include_relative tag. For that , we have to know whether this include_relative tag will read the content (code snippet) of all extension files ?
Ex : cs , java , js , xaml, dart , ect…,
Regards,
Poovarasan K
I would avoid using a different extension for you includes file. Even though I’ve seen .md, .html, and .js used for includes, there is no benefit for say .java.
Jekyll won’t execute the code in the language.
And it won’t know to highlight it with a language.
Doing this
## My heading
{% include file.java %}
Will just render as
<h2>My heading</h2>
<p>
public static... {
public main {
...
}
}
</p>
And will just be plain text on the page and not even monospaced.
Rather have a Markdown file
my_file.md
And then put markdown in it with highlighting.
```java
public static ...
public main ...
```
Then use it like this.
## My heading
{% include my_file.md %}
Then your code snippet will appear as monospaced text with Java syntax highlighting.
Or make a subdirectory and reference it
{% include snippets/my_file.md %}
You only need include relative if you want go outside includes
The file will be evaluated as liquid so for example if you have `{{ value }} in your JavaScript as I do sometimes
then that I’ll be evaluated using jekyll
So in that case use
{% raw %}
var x = ...
{{ y }}
etc.
{% endraw %}
If like you say the code will be in external repos, have a look in the forums here. There are past posts where someone wants to embed a snippet of code on page by URL
It is not part of Jekyll and I can’t remember if a plugin exists.
I guess you would want to do something like ideally.
{% github myuser/myrepo/path/to/file.java
There is a plugin you can install to do this for gists…
{% gist c08ee0f2726fd0e3909d %}
See
Also you can copy an embed url script tag straight from a gist without the plugin.
Oh by the way, an alternative to Jekyll is Docsify which has builtin feature for embedding files from a repo as code snippets
https://michaelcurrin.github.io/docsify-js-tutorial/#/?id=embed
Thanks for the update. Yes , we understood already “Jekyll won’t execute the code in the language”.
Please find our actual requirement below.
For example we have 10 repository. In each repository , we have more than 100 md files. We are converting the md files in to the html files using the Jekyll. In those md files , we would like to add the code snippet file location to render the code snippet. We will commit the code snippet files under the same location of md files to use the include_relative . Also we are using plugins for programing languages.
Find our md file tags below. Currently we have to render the code snippet like below.
{% highlight c# %}
{% include_relative CodeSnippet/test.cs %}
{% endhighlight %}
The reason for using the file with language extension ( Ex : test.cs ) , we can identify the files easily with name and extension. Also we can easily check and change the code incase of issues. Hence we don’t want add the code snippet from the md_file_1 in to md_file_2 .
Our code snippet fie only contains the required code. Hope our requirement is clear now.
That’s we are asking “ whether include_relative tag will read the content of all extension files (Ex : test.java , test.xml , test.cs) ? “
Note : we have tried the most of the using languages and it was fine.
Also we could not able to understand the details provided with Raw topic. Please explain this clearly.
Regards,
Poovarasan K
Hi
What I suggested regarding
```java
```
Is equivalent to doing
{% highlight java %}
{% endhighlight %}
Though the latter adds some more flexibility I’ve not needed like adding line numbers if you pass another argument.
I think you should just try out what you want yourself on a small scale and you’ll find out if it works with any extension or not. Programming let’s you experiment without cost of failure and can give you an answer faster than asking someone.
I used one of my jekyll sites based on jekyll new
It took me a minute to get this setup:
_includes/HelloWorld.java_my_collection/HelloWorld.javaindex.mdBoth Java files are like this:
public class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, world!");
}
}
Then on index.md
```java
{% include HelloWorld.java %}
```
```java
{% include_relative _my_collection/HelloWorld.java %}
```
And this is how it looks
Therefore as I suspected Jekyll does not care about the extension.
If the code is all in one repo it is easy.
You can use include_relative if you want to reference in a subdirectory.
e.g.
_cpp/
abc.cpp
_java/
def.java
index.md
{% include_relative _java/def.java
(And I recommend using underscore as I did above like _cpp/abc.cpp, so Jekyll does not copy cpp/abc.cpp as _site/cpp/abc.cpp because it doesn’t need to be a standalone page.)
But I don’t see the point of that. Since you code snippets aren’t standalone pages and will only be used as includes, then move then into _includes as in my earlier comment.
_includes/
cpp/
abc.cpp
java/
def.java
index.md
{% include java/def.java
I didn’t use raw in my HelloWorld.java example as i didn’t need to.
But if you ever do code like this in your files
{% ... %}
{{ ... }}
You will get an error when Jekyll runs or the code will appear missing.
Hence using raw tag.
The downside is that it will break your code. You’ll have to put {% raw %} inside your .java file.
Look up raw tag in Jekyll docs.
Thanks for the information.
I raised the query after confirming it with few language extension files only. I updated that too as notes.
I’m concerned about any possible exceptions. That is why I have raised the query.
Regards,
Poovarasan K
Jekyll is flexible but within limits.
It is not possible to predict the outcome of every use-case.
However, there are some facts that will stand true to all use-cases:
{% include ... %} and {% include_relative ... %}.source directory. Linking to files outside the source_dir is forbidden even if it is via symlinks within the source_dir, for security reasons.[a-zA-Z0-9_-()+~#@]You may be able to manage inter-repository processing by use of shell scripts (if you / your team is comfortable with that.). The pseudo-code for such a workflow would be:
--source and --destination CLI flags).excludes: key in your config file.)